From 901b6412064f763076616591d5b727a5c204acc6 Mon Sep 17 00:00:00 2001 From: Matthias Date: Wed, 5 Feb 2025 12:21:13 +0100 Subject: [PATCH 01/18] Add SDL_gamepad.inc --- units/SDL3.pas | 1 + units/SDL_gamepad.inc | 1548 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1549 insertions(+) create mode 100644 units/SDL_gamepad.inc diff --git a/units/SDL3.pas b/units/SDL3.pas index 8057ca9..52b2857 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -98,6 +98,7 @@ interface {$I SDL_mouse.inc} // 3.1.6-prev {$I SDL_keyboard.inc} // 3.1.6-prev {$I SDL_joystick.inc} // 3.1.6-prev +{$I SDL_gamepad.inc} // 3.2.0 {$I SDL_pen.inc} // 3.1.6-prev {$I SDL_touch.inc} // 3.1.6-prev {$I SDL_camera.inc} // 3.1.6-prev diff --git a/units/SDL_gamepad.inc b/units/SDL_gamepad.inc new file mode 100644 index 0000000..8d7385d --- /dev/null +++ b/units/SDL_gamepad.inc @@ -0,0 +1,1548 @@ +{ + This file is part of: + + SDL3 for Pascal + (https://github.com/PascalGameDevelopment/SDL3-for-Pascal) + SPDX-License-Identifier: Zlib +} + +{* + * # CategoryGamepad + * + * SDL provides a low-level joystick API, which just treats joysticks as an + * arbitrary pile of buttons, axes, and hat switches. If you're planning to + * write your own control configuration screen, this can give you a lot of + * flexibility, but that's a lot of work, and most things that we consider + * "joysticks" now are actually console-style gamepads. So SDL provides the + * gamepad API on top of the lower-level joystick functionality. + * + * The difference betweena joystick and a gamepad is that a gamepad tells you + * _where_ a button or axis is on the device. You don't speak to gamepads in + * terms of arbitrary numbers like "button 3" or "axis 2" but in standard + * locations: the d-pad, the shoulder buttons, triggers, A/B/X/Y (or + * X/O/Square/Triangle, if you will). + * + * One turns a joystick into a gamepad by providing a magic configuration + * string, which tells SDL the details of a specific device: when you see this + * specific hardware, if button 2 gets pressed, this is actually D-Pad Up, + * etc. + * + * SDL has many popular controllers configured out of the box, and users can + * add their own controller details through an environment variable if it's + * otherwise unknown to SDL. + * + * In order to use these functions, SDL_Init() must have been called with the + * SDL_INIT_GAMEPAD flag. This causes SDL to scan the system for gamepads, and + * load appropriate drivers. + * + * If you would like to receive gamepad updates while the application is in + * the background, you should set the following hint before calling + * SDL_Init(): SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS + * + * Gamepads support various optional features such as rumble, color LEDs, + * touchpad, gyro, etc. The support for these features varies depending on the + * controller and OS support available. You can check for LED and rumble + * capabilities at runtime by calling SDL_GetGamepadProperties() and checking + * the various capability properties. You can check for touchpad by calling + * SDL_GetNumGamepadTouchpads() and check for gyro and accelerometer by + * calling SDL_GamepadHasSensor(). + * + * By default SDL will try to use the most capable driver available, but you + * can tune which OS drivers to use with the various joystick hints in + * SDL_hints.h. + * + * Your application should always support gamepad hotplugging. On some + * platforms like Xbox, Steam Deck, etc., this is a requirement for + * certification. On other platforms, like macOS and Windows when using + * Windows.Gaming.Input, controllers may not be available at startup and will + * come in at some point after you've started processing events. + } + +{* + * The structure used to identify an SDL gamepad + * + * \since This struct is available since SDL 3.2.0. + } +type + PPSDL_Gamepad = ^PSDL_Gamepad; + PSDL_Gamepad = type Pointer; + +{* + * Standard gamepad types. + * + * This type does not necessarily map to first-party controllers from + * Microsoft/Sony/Nintendo; in many cases, third-party controllers can report + * as these, either because they were designed for a specific console, or they + * simply most closely match that console's controllers (does it have A/B/X/Y + * buttons or X/O/Square/Triangle? Does it have a touchpad? etc). + } +type + PPSDL_GamepadType = ^PSDL_GamepadType; + PSDL_GamepadType = ^TSDL_GamepadType; + TSDL_GamepadType = type Integer; +const + SDL_GAMEPAD_TYPE_UNKNOWN = TSDL_GamepadType(0); + SDL_GAMEPAD_TYPE_STANDARD = TSDL_GamepadType(1); + SDL_GAMEPAD_TYPE_XBOX360 = TSDL_GamepadType(2); + SDL_GAMEPAD_TYPE_XBOXONE = TSDL_GamepadType(3); + SDL_GAMEPAD_TYPE_PS3 = TSDL_GamepadType(4); + SDL_GAMEPAD_TYPE_PS4 = TSDL_GamepadType(5); + SDL_GAMEPAD_TYPE_PS5 = TSDL_GamepadType(6); + SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_PRO = TSDL_GamepadType(7); + SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_LEFT = TSDL_GamepadType(8); + SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_RIGHT = TSDL_GamepadType(9); + SDL_GAMEPAD_TYPE_NINTENDO_SWITCH_JOYCON_PAIR = TSDL_GamepadType(10); + SDL_GAMEPAD_TYPE_COUNT = TSDL_GamepadType(11); + +{* + * The list of buttons available on a gamepad + * + * For controllers that use a diamond pattern for the face buttons, the + * south/east/west/north buttons below correspond to the locations in the + * diamond pattern. For Xbox controllers, this would be A/B/X/Y, for Nintendo + * Switch controllers, this would be B/A/Y/X, for PlayStation controllers this + * would be Cross/Circle/Square/Triangle. + * + * For controllers that don't use a diamond pattern for the face buttons, the + * south/east/west/north buttons indicate the buttons labeled A, B, C, D, or + * 1, 2, 3, 4, or for controllers that aren't labeled, they are the primary, + * secondary, etc. buttons. + * + * The activate action is often the south button and the cancel action is + * often the east button, but in some regions this is reversed, so your game + * should allow remapping actions based on user preferences. + * + * You can query the labels for the face buttons using + * SDL_GetGamepadButtonLabel() + * + * \since This enum is available since SDL 3.2.0. + } +type + PPSDL_GamepadButton = ^PSDL_GamepadButton; + PSDL_GamepadButton = ^TSDL_GamepadButton; + TSDL_GamepadButton = type Integer; +const + SDL_GAMEPAD_BUTTON_INVALID = TSDL_GamepadButton(-1); + SDL_GAMEPAD_BUTTON_SOUTH = TSDL_GamepadButton(0); {*< Bottom face button (e.g. Xbox A button) } + SDL_GAMEPAD_BUTTON_EAST = TSDL_GamepadButton(1); {*< Right face button (e.g. Xbox B button) } + SDL_GAMEPAD_BUTTON_WEST = TSDL_GamepadButton(2); {*< Left face button (e.g. Xbox X button) } + SDL_GAMEPAD_BUTTON_NORTH = TSDL_GamepadButton(3); {*< Top face button (e.g. Xbox Y button) } + SDL_GAMEPAD_BUTTON_BACK = TSDL_GamepadButton(4); + SDL_GAMEPAD_BUTTON_GUIDE = TSDL_GamepadButton(5); + SDL_GAMEPAD_BUTTON_START = TSDL_GamepadButton(6); + SDL_GAMEPAD_BUTTON_LEFT_STICK = TSDL_GamepadButton(7); + SDL_GAMEPAD_BUTTON_RIGHT_STICK = TSDL_GamepadButton(8); + SDL_GAMEPAD_BUTTON_LEFT_SHOULDER = TSDL_GamepadButton(9); + SDL_GAMEPAD_BUTTON_RIGHT_SHOULDER = TSDL_GamepadButton(10); + SDL_GAMEPAD_BUTTON_DPAD_UP = TSDL_GamepadButton(11); + SDL_GAMEPAD_BUTTON_DPAD_DOWN = TSDL_GamepadButton(12); + SDL_GAMEPAD_BUTTON_DPAD_LEFT = TSDL_GamepadButton(13); + SDL_GAMEPAD_BUTTON_DPAD_RIGHT = TSDL_GamepadButton(14); + SDL_GAMEPAD_BUTTON_MISC1 = TSDL_GamepadButton(15); {*< Additional button (e.g. Xbox Series X share button, PS5 microphone button, Nintendo Switch Pro capture button, Amazon Luna microphone button, Google Stadia capture button) } + SDL_GAMEPAD_BUTTON_RIGHT_PADDLE1 = TSDL_GamepadButton(16); {*< Upper or primary paddle, under your right hand (e.g. Xbox Elite paddle P1) } + SDL_GAMEPAD_BUTTON_LEFT_PADDLE1 = TSDL_GamepadButton(17); {*< Upper or primary paddle, under your left hand (e.g. Xbox Elite paddle P3) } + SDL_GAMEPAD_BUTTON_RIGHT_PADDLE2 = TSDL_GamepadButton(18); {*< Lower or secondary paddle, under your right hand (e.g. Xbox Elite paddle P2) } + SDL_GAMEPAD_BUTTON_LEFT_PADDLE2 = TSDL_GamepadButton(19); {*< Lower or secondary paddle, under your left hand (e.g. Xbox Elite paddle P4) } + SDL_GAMEPAD_BUTTON_TOUCHPAD = TSDL_GamepadButton(20); {*< PS4/PS5 touchpad button } + SDL_GAMEPAD_BUTTON_MISC2 = TSDL_GamepadButton(21); {*< Additional button } + SDL_GAMEPAD_BUTTON_MISC3 = TSDL_GamepadButton(22); {*< Additional button } + SDL_GAMEPAD_BUTTON_MISC4 = TSDL_GamepadButton(23); {*< Additional button } + SDL_GAMEPAD_BUTTON_MISC5 = TSDL_GamepadButton(24); {*< Additional button } + SDL_GAMEPAD_BUTTON_MISC6 = TSDL_GamepadButton(25); {*< Additional button } + SDL_GAMEPAD_BUTTON_COUNT = TSDL_GamepadButton(26); + +{* + * The set of gamepad button labels + * + * This isn't a complete set, just the face buttons to make it easy to show + * button prompts. + * + * For a complete set, you should look at the button and gamepad type and have + * a set of symbols that work well with your art style. + * + * \since This enum is available since SDL 3.2.0. + } +type + PPSDL_GamepadButtonLabel = ^PSDL_GamepadButtonLabel; + PSDL_GamepadButtonLabel = ^TSDL_GamepadButtonLabel; + TSDL_GamepadButtonLabel = type Integer; +const + SDL_GAMEPAD_BUTTON_LABEL_UNKNOWN = TSDL_GamepadButtonLabel(0); + SDL_GAMEPAD_BUTTON_LABEL_A = TSDL_GamepadButtonLabel(1); + SDL_GAMEPAD_BUTTON_LABEL_B = TSDL_GamepadButtonLabel(2); + SDL_GAMEPAD_BUTTON_LABEL_X = TSDL_GamepadButtonLabel(3); + SDL_GAMEPAD_BUTTON_LABEL_Y = TSDL_GamepadButtonLabel(4); + SDL_GAMEPAD_BUTTON_LABEL_CROSS = TSDL_GamepadButtonLabel(5); + SDL_GAMEPAD_BUTTON_LABEL_CIRCLE = TSDL_GamepadButtonLabel(6); + SDL_GAMEPAD_BUTTON_LABEL_SQUARE = TSDL_GamepadButtonLabel(7); + SDL_GAMEPAD_BUTTON_LABEL_TRIANGLE = TSDL_GamepadButtonLabel(8); + +{* + * The list of axes available on a gamepad + * + * Thumbstick axis values range from SDL_JOYSTICK_AXIS_MIN to + * SDL_JOYSTICK_AXIS_MAX, and are centered within ~8000 of zero, though + * advanced UI will allow users to set or autodetect the dead zone, which + * varies between gamepads. + * + * Trigger axis values range from 0 (released) to SDL_JOYSTICK_AXIS_MAX (fully + * pressed) when reported by SDL_GetGamepadAxis(). Note that this is not the + * same range that will be reported by the lower-level SDL_GetJoystickAxis(). + * + * \since This enum is available since SDL 3.2.0. + } +type + PSDL_GamepadAxis = ^TSDL_GamepadAxis; + TSDL_GamepadAxis = Longint; +Const + SDL_GAMEPAD_AXIS_INVALID = TSDL_GamepadAxis(-1); + SDL_GAMEPAD_AXIS_LEFTX = TSDL_GamepadAxis(0); + SDL_GAMEPAD_AXIS_LEFTY = TSDL_GamepadAxis(1); + SDL_GAMEPAD_AXIS_RIGHTX = TSDL_GamepadAxis(2); + SDL_GAMEPAD_AXIS_RIGHTY = TSDL_GamepadAxis(3); + SDL_GAMEPAD_AXIS_LEFT_TRIGGER = TSDL_GamepadAxis(4); + SDL_GAMEPAD_AXIS_RIGHT_TRIGGER = TSDL_GamepadAxis(5); + SDL_GAMEPAD_AXIS_COUNT = TSDL_GamepadAxis(6); + +{* + * Types of gamepad control bindings. + * + * A gamepad is a collection of bindings that map arbitrary joystick buttons, + * axes and hat switches to specific positions on a generic console-style + * gamepad. This enum is used as part of SDL_GamepadBinding to specify those + * mappings. + * + * \since This enum is available since SDL 3.2.0. + } +type + PSDL_GamepadBindingType = ^TSDL_GamepadBindingType; + TSDL_GamepadBindingType = Longint; +Const + SDL_GAMEPAD_BINDTYPE_NONE = TSDL_GamepadBindingType(0); + SDL_GAMEPAD_BINDTYPE_BUTTON = TSDL_GamepadBindingType(1); + SDL_GAMEPAD_BINDTYPE_AXIS = TSDL_GamepadBindingType(2); + SDL_GAMEPAD_BINDTYPE_HAT = TSDL_GamepadBindingType(3); + +{* + * A mapping between one joystick input to a gamepad control. + * + * A gamepad has a collection of several bindings, to say, for example, when + * joystick button number 5 is pressed, that should be treated like the + * gamepad's "start" button. + * + * SDL has these bindings built-in for many popular controllers, and can add + * more with a simple text string. Those strings are parsed into a collection + * of these structs to make it easier to operate on the data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadBindings + } +type + PPSDL_GamepadBinding = ^PSDL_GamepadBinding; + PSDL_GamepadBinding = ^TSDL_GamepadBinding; + TSDL_GamepadBinding = record + input_type : TSDL_GamepadBindingType; + input : record + case longint of + 0 : ( button : cint ); + 1 : ( axis : record + axis : cint; + axis_min : cint; + axis_max : cint; + end ); + 2 : ( hat : record + hat : cint; + hat_mask : cint; + end ); + end; + output_type : TSDL_GamepadBindingType; + output : record + case longint of + 0 : ( button : TSDL_GamepadButton ); + 1 : ( axis : record + axis : TSDL_GamepadAxis; + axis_min : cint; + axis_max : cint; + end ); + end; + end; + +{* + * Add support for gamepads that SDL is unaware of or change the binding of an + * existing gamepad. + * + * The mapping string has the format "GUID,name,mapping", where GUID is the + * string value from SDL_GUIDToString(), name is the human readable string for + * the device and mappings are gamepad mappings to joystick ones. Under + * Windows there is a reserved GUID of "xinput" that covers all XInput + * devices. The mapping format for joystick is: + * + * - `bX`: a joystick button, index X + * - `hX.Y`: hat X with value Y + * - `aX`: axis X of the joystick + * + * Buttons can be used as a gamepad axes and vice versa. + * + * If a device with this GUID is already plugged in, SDL will generate an + * SDL_EVENT_GAMEPAD_ADDED event. + * + * This string shows an example of a valid mapping for a gamepad: + * + * ```c + * "341a3608000000000000504944564944,Afterglow PS3 Controller,a: b1,b: b2,y: b3,x: b0,start: b9,guide: b12,back: b8,dpup: h0.1,dpleft: h0.8,dpdown: h0.4,dpright: h0.2,leftshoulder: b4,rightshoulder: b5,leftstick: b10,rightstick: b11,leftx: a0,lefty: a1,rightx: a2,righty: a3,lefttrigger: b6,righttrigger: b7" + * ``` + * + * \param mapping the mapping string. + * \returns 1 if a new mapping is added, 0 if an existing mapping is updated, + * -1 on failure; call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddGamepadMappingsFromFile + * \sa SDL_AddGamepadMappingsFromIO + * \sa SDL_GetGamepadMapping + * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED + } +function SDL_AddGamepadMapping(mapping: PAnsiChar): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AddGamepadMapping' {$ENDIF} {$ENDIF}; + +{* + * Load a set of gamepad mappings from an SDL_IOStream. + * + * You can call this function several times, if needed, to load different + * database files. + * + * If a new mapping is loaded for an already known gamepad GUID, the later + * version will overwrite the one currently loaded. + * + * Any new mappings for already plugged in controllers will generate + * SDL_EVENT_GAMEPAD_ADDED events. + * + * Mappings not belonging to the current platform or with no platform field + * specified will be ignored (i.e. mappings for Linux will be ignored in + * Windows, etc). + * + * This function will load the text database entirely in memory before + * processing it, so take this into consideration if you are in a memory + * constrained environment. + * + * \param src the data stream for the mappings to be added. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. + * \returns the number of mappings added or -1 on failure; call SDL_GetError() + * for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddGamepadMapping + * \sa SDL_AddGamepadMappingsFromFile + * \sa SDL_GetGamepadMapping + * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED + } +function SDL_AddGamepadMappingsFromIO(src: PSDL_IOStream; closeio: cbool): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AddGamepadMappingsFromIO' {$ENDIF} {$ENDIF}; + +{* + * Load a set of gamepad mappings from a file. + * + * You can call this function several times, if needed, to load different + * database files. + * + * If a new mapping is loaded for an already known gamepad GUID, the later + * version will overwrite the one currently loaded. + * + * Any new mappings for already plugged in controllers will generate + * SDL_EVENT_GAMEPAD_ADDED events. + * + * Mappings not belonging to the current platform or with no platform field + * specified will be ignored (i.e. mappings for Linux will be ignored in + * Windows, etc). + * + * \param file the mappings file to load. + * \returns the number of mappings added or -1 on failure; call SDL_GetError() + * for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddGamepadMapping + * \sa SDL_AddGamepadMappingsFromIO + * \sa SDL_GetGamepadMapping + * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_HINT_GAMECONTROLLERCONFIG + * \sa SDL_HINT_GAMECONTROLLERCONFIG_FILE + * \sa SDL_EVENT_GAMEPAD_ADDED + } +function SDL_AddGamepadMappingsFromFile(file_: PAnsiChar): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AddGamepadMappingsFromFile' {$ENDIF} {$ENDIF}; + +{* + * Reinitialize the SDL mapping database to its initial state. + * + * This will generate gamepad events as needed if device mappings change. + * + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_ReloadGamepadMappings: cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReloadGamepadMappings' {$ENDIF} {$ENDIF}; + +{* + * Get the current gamepad mappings. + * + * \param count a Pointer filled in with the number of mappings returned, can + * be nil. + * \returns an array of the mapping strings, nil-terminated, or nil on + * failure; call SDL_GetError() for more information. This is a + * single allocation that should be freed with SDL_free() when it is + * no longer needed. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetGamepadMappings(count: pcint):PPAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadMappings' {$ENDIF} {$ENDIF}; + +{* + * Get the gamepad mapping string for a given GUID. + * + * \param guid a structure containing the GUID for which a mapping is desired. + * \returns a mapping string or nil on failure; call SDL_GetError() for more + * information. This should be freed with SDL_free() when it is no + * longer needed. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoystickGUIDForID + * \sa SDL_GetJoystickGUID + } +function SDL_GetGamepadMappingForGUID(guid: TSDL_GUID): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadMappingForGUID' {$ENDIF} {$ENDIF}; + +{* + * Get the current mapping of a gamepad. + * + * Details about mappings are discussed with SDL_AddGamepadMapping(). + * + * \param gamepad the gamepad you want to get the current mapping for. + * \returns a string that has the gamepad's mapping or nil if no mapping is + * available; call SDL_GetError() for more information. This should + * be freed with SDL_free() when it is no longer needed. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddGamepadMapping + * \sa SDL_GetGamepadMappingForID + * \sa SDL_GetGamepadMappingForGUID + * \sa SDL_SetGamepadMapping + } +function SDL_GetGamepadMapping(gamepad: PSDL_Gamepad): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadMapping' {$ENDIF} {$ENDIF}; + +{* + * Set the current mapping of a joystick or gamepad. + * + * Details about mappings are discussed with SDL_AddGamepadMapping(). + * + * \param instance_id the joystick instance ID. + * \param mapping the mapping to use for this device, or nil to clear the + * mapping. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddGamepadMapping + * \sa SDL_GetGamepadMapping + } +function SDL_SetGamepadMapping(instance_id: TSDL_JoystickID; mapping: PAnsiChar): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetGamepadMapping' {$ENDIF} {$ENDIF}; + +{* + * Return whether a gamepad is currently connected. + * + * \returns true if a gamepad is connected, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepads + } +function SDL_HasGamepad: cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HasGamepad' {$ENDIF} {$ENDIF}; + +{* + * Get a list of currently connected gamepads. + * + * \param count a Pointer filled in with the number of gamepads returned, may + * be nil. + * \returns a 0 terminated array of joystick instance IDs or nil on failure; + * call SDL_GetError() for more information. This should be freed + * with SDL_free() when it is no longer needed. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HasGamepad + * \sa SDL_OpenGamepad + } +function SDL_GetGamepads(count: pcint): PSDL_JoystickID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepads' {$ENDIF} {$ENDIF}; + +{* + * Check if the given joystick is supported by the gamepad interface. + * + * \param instance_id the joystick instance ID. + * \returns true if the given joystick is supported by the gamepad interface, + * false if it isn't or it's an invalid index. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetJoysticks + * \sa SDL_OpenGamepad + } +function SDL_IsGamepad(instance_id: TSDL_JoystickID): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IsGamepad' {$ENDIF} {$ENDIF}; + +{* + * Get the implementation dependent name of a gamepad. + * + * This can be called before any gamepads are opened. + * + * \param instance_id the joystick instance ID. + * \returns the name of the selected gamepad. If no name can be found, this + * function returns nil; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadName + * \sa SDL_GetGamepads + } +function SDL_GetGamepadNameForID(instance_id: TSDL_JoystickID): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadNameForID' {$ENDIF} {$ENDIF}; + +{* + * Get the implementation dependent path of a gamepad. + * + * This can be called before any gamepads are opened. + * + * \param instance_id the joystick instance ID. + * \returns the path of the selected gamepad. If no path can be found, this + * function returns nil; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadPath + * \sa SDL_GetGamepads + } +function SDL_GetGamepadPathForID(instance_id: TSDL_JoystickID): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadPathForID' {$ENDIF} {$ENDIF}; + +{* + * Get the player index of a gamepad. + * + * This can be called before any gamepads are opened. + * + * \param instance_id the joystick instance ID. + * \returns the player index of a gamepad, or -1 if it's not available. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadPlayerIndex + * \sa SDL_GetGamepads + } +function SDL_GetGamepadPlayerIndexForID(instance_id: TSDL_JoystickID): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadPlayerIndexForID' {$ENDIF} {$ENDIF}; + +{* + * Get the implementation-dependent GUID of a gamepad. + * + * This can be called before any gamepads are opened. + * + * \param instance_id the joystick instance ID. + * \returns the GUID of the selected gamepad. If called on an invalid index, + * this function returns a zero GUID. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GUIDToString + * \sa SDL_GetGamepads + } +function SDL_GetGamepadGUIDForID(instance_id: TSDL_JoystickID): TSDL_GUID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadGUIDForID' {$ENDIF} {$ENDIF}; + +{* + * Get the USB vendor ID of a gamepad, if available. + * + * This can be called before any gamepads are opened. If the vendor ID isn't + * available this function returns 0. + * + * \param instance_id the joystick instance ID. + * \returns the USB vendor ID of the selected gamepad. If called on an invalid + * index, this function returns zero. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadVendor + * \sa SDL_GetGamepads + } +function SDL_GetGamepadVendorForID(instance_id: TSDL_JoystickID): cuint16; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadVendorForID' {$ENDIF} {$ENDIF}; + +{* + * Get the USB product ID of a gamepad, if available. + * + * This can be called before any gamepads are opened. If the product ID isn't + * available this function returns 0. + * + * \param instance_id the joystick instance ID. + * \returns the USB product ID of the selected gamepad. If called on an + * invalid index, this function returns zero. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadProduct + * \sa SDL_GetGamepads + } +function SDL_GetGamepadProductForID(instance_id: TSDL_JoystickID): cuint16; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadProductForID' {$ENDIF} {$ENDIF}; + +{* + * Get the product version of a gamepad, if available. + * + * This can be called before any gamepads are opened. If the product version + * isn't available this function returns 0. + * + * \param instance_id the joystick instance ID. + * \returns the product version of the selected gamepad. If called on an + * invalid index, this function returns zero. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadProductVersion + * \sa SDL_GetGamepads + } +function SDL_GetGamepadProductVersionForID(instance_id: TSDL_JoystickID): cuint16; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadProductVersionForID' {$ENDIF} {$ENDIF}; + +{* + * Get the type of a gamepad. + * + * This can be called before any gamepads are opened. + * + * \param instance_id the joystick instance ID. + * \returns the gamepad type. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadType + * \sa SDL_GetGamepads + * \sa SDL_GetRealGamepadTypeForID + } +function SDL_GetGamepadTypeForID(instance_id: TSDL_JoystickID): TSDL_GamepadType; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadTypeForID' {$ENDIF} {$ENDIF}; + +{* + * Get the type of a gamepad, ignoring any mapping override. + * + * This can be called before any gamepads are opened. + * + * \param instance_id the joystick instance ID. + * \returns the gamepad type. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadTypeForID + * \sa SDL_GetGamepads + * \sa SDL_GetRealGamepadType + } +function SDL_GetRealGamepadTypeForID(instance_id: TSDL_JoystickID): TSDL_GamepadType; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetRealGamepadTypeForID' {$ENDIF} {$ENDIF}; + +{* + * Get the mapping of a gamepad. + * + * This can be called before any gamepads are opened. + * + * \param instance_id the joystick instance ID. + * \returns the mapping string. Returns nil if no mapping is available. This + * should be freed with SDL_free() when it is no longer needed. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepads + * \sa SDL_GetGamepadMapping + } +function SDL_GetGamepadMappingForID(instance_id: TSDL_JoystickID): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadMappingForID' {$ENDIF} {$ENDIF}; + +{* + * Open a gamepad for use. + * + * \param instance_id the joystick instance ID. + * \returns a gamepad identifier or nil if an error occurred; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseGamepad + * \sa SDL_IsGamepad + } +function SDL_OpenGamepad(instance_id: TSDL_JoystickID): PSDL_Gamepad; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_OpenGamepad' {$ENDIF} {$ENDIF}; + +{* + * Get the SDL_Gamepad associated with a joystick instance ID, if it has been + * opened. + * + * \param instance_id the joystick instance ID of the gamepad. + * \returns an SDL_Gamepad on success or nil on failure or if it hasn't been + * opened yet; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetGamepadFromID(instance_id: TSDL_JoystickID): PSDL_Gamepad; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadFromID' {$ENDIF} {$ENDIF}; + +{* + * Get the SDL_Gamepad associated with a player index. + * + * \param player_index the player index, which different from the instance ID. + * \returns the SDL_Gamepad associated with a player index. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadPlayerIndex + * \sa SDL_SetGamepadPlayerIndex + } +function SDL_GetGamepadFromPlayerIndex(player_index: cint): PSDL_Gamepad; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadFromPlayerIndex' {$ENDIF} {$ENDIF}; + +{* + * Get the properties associated with an opened gamepad. + * + * These properties are shared with the underlying joystick object. + * + * The following read-only properties are provided by SDL: + * + * - `SDL_PROP_GAMEPAD_CAP_MONO_LED_BOOLEAN`: true if this gamepad has an LED + * that has adjustable brightness + * - `SDL_PROP_GAMEPAD_CAP_RGB_LED_BOOLEAN`: true if this gamepad has an LED + * that has adjustable color + * - `SDL_PROP_GAMEPAD_CAP_PLAYER_LED_BOOLEAN`: true if this gamepad has a + * player LED + * - `SDL_PROP_GAMEPAD_CAP_RUMBLE_BOOLEAN`: true if this gamepad has + * left/right rumble + * - `SDL_PROP_GAMEPAD_CAP_TRIGGER_RUMBLE_BOOLEAN`: true if this gamepad has + * simple trigger rumble + * + * \param gamepad a gamepad identifier previously returned by + * SDL_OpenGamepad(). + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetGamepadProperties(gamepad: PSDL_Gamepad): TSDL_PropertiesID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadProperties' {$ENDIF} {$ENDIF}; + +const + SDL_PROP_GAMEPAD_CAP_MONO_LED_BOOLEAN = SDL_PROP_JOYSTICK_CAP_MONO_LED_BOOLEAN; + SDL_PROP_GAMEPAD_CAP_RGB_LED_BOOLEAN = SDL_PROP_JOYSTICK_CAP_RGB_LED_BOOLEAN; + SDL_PROP_GAMEPAD_CAP_PLAYER_LED_BOOLEAN = SDL_PROP_JOYSTICK_CAP_PLAYER_LED_BOOLEAN; + SDL_PROP_GAMEPAD_CAP_RUMBLE_BOOLEAN = SDL_PROP_JOYSTICK_CAP_RUMBLE_BOOLEAN; + SDL_PROP_GAMEPAD_CAP_TRIGGER_RUMBLE_BOOLEAN = SDL_PROP_JOYSTICK_CAP_TRIGGER_RUMBLE_BOOLEAN; + +{* + * Get the instance ID of an opened gamepad. + * + * \param gamepad a gamepad identifier previously returned by + * SDL_OpenGamepad(). + * \returns the instance ID of the specified gamepad on success or 0 on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetGamepadID(gamepad: PSDL_Gamepad): TSDL_JoystickID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadID' {$ENDIF} {$ENDIF}; + +{* + * Get the implementation-dependent name for an opened gamepad. + * + * \param gamepad a gamepad identifier previously returned by + * SDL_OpenGamepad(). + * \returns the implementation dependent name for the gamepad, or nil if + * there is no name or the identifier passed is invalid. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadNameForID + } + +function SDL_GetGamepadName(gamepad: PSDL_Gamepad): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadName' {$ENDIF} {$ENDIF}; + +{* + * Get the implementation-dependent path for an opened gamepad. + * + * \param gamepad a gamepad identifier previously returned by + * SDL_OpenGamepad(). + * \returns the implementation dependent path for the gamepad, or nil if + * there is no path or the identifier passed is invalid. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadPathForID + } + +function SDL_GetGamepadPath(gamepad: PSDL_Gamepad): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadPath' {$ENDIF} {$ENDIF}; + +{* + * Get the type of an opened gamepad. + * + * \param gamepad the gamepad object to query. + * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not + * available. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadTypeForID + } +function SDL_GetGamepadType(gamepad: PSDL_Gamepad): TSDL_GamepadType; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadType' {$ENDIF} {$ENDIF}; + +{* + * Get the type of an opened gamepad, ignoring any mapping override. + * + * \param gamepad the gamepad object to query. + * \returns the gamepad type, or SDL_GAMEPAD_TYPE_UNKNOWN if it's not + * available. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetRealGamepadTypeForID + } +function SDL_GetRealGamepadType(gamepad: PSDL_Gamepad): TSDL_GamepadType; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetRealGamepadType' {$ENDIF} {$ENDIF}; + +{* + * Get the player index of an opened gamepad. + * + * For XInput gamepads this returns the XInput user index. + * + * \param gamepad the gamepad object to query. + * \returns the player index for gamepad, or -1 if it's not available. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetGamepadPlayerIndex + } +function SDL_GetGamepadPlayerIndex(gamepad: PSDL_Gamepad): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadPlayerIndex' {$ENDIF} {$ENDIF}; + +{* + * Set the player index of an opened gamepad. + * + * \param gamepad the gamepad object to adjust. + * \param player_index player index to assign to this gamepad, or -1 to clear + * the player index and turn off player LEDs. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadPlayerIndex + } +function SDL_SetGamepadPlayerIndex(gamepad: PSDL_Gamepad; player_index: cint): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetGamepadPlayerIndex' {$ENDIF} {$ENDIF}; + +{* + * Get the USB vendor ID of an opened gamepad, if available. + * + * If the vendor ID isn't available this function returns 0. + * + * \param gamepad the gamepad object to query. + * \returns the USB vendor ID, or zero if unavailable. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadVendorForID + } +function SDL_GetGamepadVendor(gamepad: PSDL_Gamepad): cuint16; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadVendor' {$ENDIF} {$ENDIF}; + +{* + * Get the USB product ID of an opened gamepad, if available. + * + * If the product ID isn't available this function returns 0. + * + * \param gamepad the gamepad object to query. + * \returns the USB product ID, or zero if unavailable. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadProductForID + } +function SDL_GetGamepadProduct(gamepad: PSDL_Gamepad): cuint16; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadProduct' {$ENDIF} {$ENDIF}; + +{* + * Get the product version of an opened gamepad, if available. + * + * If the product version isn't available this function returns 0. + * + * \param gamepad the gamepad object to query. + * \returns the USB product version, or zero if unavailable. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadProductVersionForID + } +function SDL_GetGamepadProductVersion(gamepad: PSDL_Gamepad): cuint16; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadProductVersion' {$ENDIF} {$ENDIF}; + +{* + * Get the firmware version of an opened gamepad, if available. + * + * If the firmware version isn't available this function returns 0. + * + * \param gamepad the gamepad object to query. + * \returns the gamepad firmware version, or zero if unavailable. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetGamepadFirmwareVersion(gamepad: PSDL_Gamepad): cuint16; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadFirmwareVersion' {$ENDIF} {$ENDIF}; + +{* + * Get the serial number of an opened gamepad, if available. + * + * Returns the serial number of the gamepad, or nil if it is not available. + * + * \param gamepad the gamepad object to query. + * \returns the serial number, or nil if unavailable. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetGamepadSerial(gamepad: PSDL_Gamepad): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadSerial' {$ENDIF} {$ENDIF}; + +{* + * Get the Steam Input handle of an opened gamepad, if available. + * + * Returns an InputHandle_t for the gamepad that can be used with Steam Input + * API: https://partner.steamgames.com/doc/api/ISteamInput + * + * \param gamepad the gamepad object to query. + * \returns the gamepad handle, or 0 if unavailable. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetGamepadSteamHandle(gamepad: PSDL_Gamepad): cuint64; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadSteamHandle' {$ENDIF} {$ENDIF}; + +{* + * Get the connection state of a gamepad. + * + * \param gamepad the gamepad object to query. + * \returns the connection state on success or + * `SDL_JOYSTICK_CONNECTION_INVALID` on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetGamepadConnectionState(gamepad: PSDL_Gamepad): TSDL_JoystickConnectionState; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadConnectionState' {$ENDIF} {$ENDIF}; + +{* + * Get the battery state of a gamepad. + * + * You should never take a battery status as absolute truth. Batteries + * (especially failing batteries) are delicate hardware, and the values + * reported here are best estimates based on what that hardware reports. It's + * not uncommon for older batteries to lose stored power much faster than it + * reports, or completely drain when reporting it has 20 percent left, etc. + * + * \param gamepad the gamepad object to query. + * \param percent a Pointer filled in with the percentage of battery life + * left, between 0 and 100, or nil to ignore. This will be + * filled in with -1 we can't determine a value or there is no + * battery. + * \returns the current battery state. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetGamepadPowerInfo(gamepad: PSDL_Gamepad; percent: pcint): TSDL_PowerState; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadPowerInfo' {$ENDIF} {$ENDIF}; + +{* + * Check if a gamepad has been opened and is currently connected. + * + * \param gamepad a gamepad identifier previously returned by + * SDL_OpenGamepad(). + * \returns true if the gamepad has been opened and is currently connected, or + * false if not. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GamepadConnected(gamepad: PSDL_Gamepad): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GamepadConnected' {$ENDIF} {$ENDIF}; + +{* + * Get the underlying joystick from a gamepad. + * + * This function will give you a SDL_Joystick object, which allows you to use + * the SDL_Joystick functions with a SDL_Gamepad object. This would be useful + * for getting a joystick's position at any given time, even if it hasn't + * moved (moving it would produce an event, which would have the axis' value). + * + * The Pointer returned is owned by the SDL_Gamepad. You should not call + * SDL_CloseJoystick() on it, for example, since doing so will likely cause + * SDL to crash. + * + * \param gamepad the gamepad object that you want to get a joystick from. + * \returns an SDL_Joystick object, or nil on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetGamepadJoystick(gamepad: PSDL_Gamepad): PSDL_Joystick; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadJoystick' {$ENDIF} {$ENDIF}; + +{* + * Set the state of gamepad event processing. + * + * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself + * and check the state of the gamepad when you want gamepad information. + * + * \param enabled whether to process gamepad events or not. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GamepadEventsEnabled + * \sa SDL_UpdateGamepads + } +procedure SDL_SetGamepadEventsEnabled(enabled: cbool); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetGamepadEventsEnabled' {$ENDIF} {$ENDIF}; + +{* + * Query the state of gamepad event processing. + * + * If gamepad events are disabled, you must call SDL_UpdateGamepads() yourself + * and check the state of the gamepad when you want gamepad information. + * + * \returns true if gamepad events are being processed, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetGamepadEventsEnabled + } +function SDL_GamepadEventsEnabled: cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GamepadEventsEnabled' {$ENDIF} {$ENDIF}; + +{* + * Get the SDL joystick layer bindings for a gamepad. + * + * \param gamepad a gamepad. + * \param count a Pointer filled in with the number of bindings returned. + * \returns a nil terminated array of pointers to bindings or nil on + * failure; call SDL_GetError() for more information. This is a + * single allocation that should be freed with SDL_free() when it is + * no longer needed. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetGamepadBindings(gamepad: PSDL_Gamepad; count: pcint):PPSDL_GamepadBinding; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadBindings' {$ENDIF} {$ENDIF}; + +{* + * Manually pump gamepad updates if not using the loop. + * + * This function is called automatically by the event loop if events are + * enabled. Under such circumstances, it will not be necessary to call this + * function. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_UpdateGamepads; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UpdateGamepads' {$ENDIF} {$ENDIF}; + +{* + * Convert a string into SDL_GamepadType enum. + * + * This function is called internally to translate SDL_Gamepad mapping strings + * for the underlying joystick device into the consistent SDL_Gamepad mapping. + * You do not normally need to call this function unless you are parsing + * SDL_Gamepad mappings in your own code. + * + * \param str string representing a SDL_GamepadType type. + * \returns the SDL_GamepadType enum corresponding to the input string, or + * `SDL_GAMEPAD_TYPE_UNKNOWN` if no match was found. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadStringForType + } +function SDL_GetGamepadTypeFromString(str: PAnsiChar): TSDL_GamepadType; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadTypeFromString' {$ENDIF} {$ENDIF}; + +{* + * Convert from an SDL_GamepadType enum to a string. + * + * \param type an enum value for a given SDL_GamepadType. + * \returns a string for the given type, or nil if an invalid type is + * specified. The string returned is of the format used by + * SDL_Gamepad mapping strings. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadTypeFromString + } +function SDL_GetGamepadStringForType(type_: TSDL_GamepadType): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadStringForType' {$ENDIF} {$ENDIF}; + +{* + * Convert a string into SDL_GamepadAxis enum. + * + * This function is called internally to translate SDL_Gamepad mapping strings + * for the underlying joystick device into the consistent SDL_Gamepad mapping. + * You do not normally need to call this function unless you are parsing + * SDL_Gamepad mappings in your own code. + * + * Note specially that "righttrigger" and "lefttrigger" map to + * `SDL_GAMEPAD_AXIS_RIGHT_TRIGGER` and `SDL_GAMEPAD_AXIS_LEFT_TRIGGER`, + * respectively. + * + * \param str string representing a SDL_Gamepad axis. + * \returns the SDL_GamepadAxis enum corresponding to the input string, or + * `SDL_GAMEPAD_AXIS_INVALID` if no match was found. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadStringForAxis + } +function SDL_GetGamepadAxisFromString(str: PAnsiChar): TSDL_GamepadAxis; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadAxisFromString' {$ENDIF} {$ENDIF}; + +{* + * Convert from an SDL_GamepadAxis enum to a string. + * + * \param axis an enum value for a given SDL_GamepadAxis. + * \returns a string for the given axis, or nil if an invalid axis is + * specified. The string returned is of the format used by + * SDL_Gamepad mapping strings. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadAxisFromString + } +function SDL_GetGamepadStringForAxis(axis: TSDL_GamepadAxis): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadStringForAxis' {$ENDIF} {$ENDIF}; + +{* + * Query whether a gamepad has a given axis. + * + * This merely reports whether the gamepad's mapping defined this axis, as + * that is all the information SDL has about the physical device. + * + * \param gamepad a gamepad. + * \param axis an axis enum value (an SDL_GamepadAxis value). + * \returns true if the gamepad has this axis, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GamepadHasButton + * \sa SDL_GetGamepadAxis + } +function SDL_GamepadHasAxis(gamepad: PSDL_Gamepad; axis: TSDL_GamepadAxis): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GamepadHasAxis' {$ENDIF} {$ENDIF}; + +{* + * Get the current state of an axis control on a gamepad. + * + * The axis indices start at index 0. + * + * For thumbsticks, the state is a value ranging from -32768 (up/left) to + * 32767 (down/right). + * + * Triggers range from 0 when released to 32767 when fully pressed, and never + * return a negative value. Note that this differs from the value reported by + * the lower-level SDL_GetJoystickAxis(), which normally uses the full range. + * + * \param gamepad a gamepad. + * \param axis an axis index (one of the SDL_GamepadAxis values). + * \returns axis state (including 0) on success or 0 (also) on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GamepadHasAxis + * \sa SDL_GetGamepadButton + } +function SDL_GetGamepadAxis(gamepad: PSDL_Gamepad; axis: TSDL_GamepadAxis): cint16; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadAxis' {$ENDIF} {$ENDIF}; + +{* + * Convert a string into an SDL_GamepadButton enum. + * + * This function is called internally to translate SDL_Gamepad mapping strings + * for the underlying joystick device into the consistent SDL_Gamepad mapping. + * You do not normally need to call this function unless you are parsing + * SDL_Gamepad mappings in your own code. + * + * \param str string representing a SDL_Gamepad axis. + * \returns the SDL_GamepadButton enum corresponding to the input string, or + * `SDL_GAMEPAD_BUTTON_INVALID` if no match was found. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadStringForButton + } +function SDL_GetGamepadButtonFromString(str: PAnsiChar): TSDL_GamepadButton; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadButtonFromString' {$ENDIF} {$ENDIF}; + +{* + * Convert from an SDL_GamepadButton enum to a string. + * + * \param button an enum value for a given SDL_GamepadButton. + * \returns a string for the given button, or nil if an invalid button is + * specified. The string returned is of the format used by + * SDL_Gamepad mapping strings. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadButtonFromString + } +function SDL_GetGamepadStringForButton(button: TSDL_GamepadButton): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadStringForButton' {$ENDIF} {$ENDIF}; + +{* + * Query whether a gamepad has a given button. + * + * This merely reports whether the gamepad's mapping defined this button, as + * that is all the information SDL has about the physical device. + * + * \param gamepad a gamepad. + * \param button a button enum value (an SDL_GamepadButton value). + * \returns true if the gamepad has this button, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GamepadHasAxis + } +function SDL_GamepadHasButton(gamepad: PSDL_Gamepad; button: TSDL_GamepadButton): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GamepadHasButton' {$ENDIF} {$ENDIF}; + +{* + * Get the current state of a button on a gamepad. + * + * \param gamepad a gamepad. + * \param button a button index (one of the SDL_GamepadButton values). + * \returns true if the button is pressed, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GamepadHasButton + * \sa SDL_GetGamepadAxis + } +function SDL_GetGamepadButton(gamepad: PSDL_Gamepad; button: TSDL_GamepadButton): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadButton' {$ENDIF} {$ENDIF}; + +{* + * Get the label of a button on a gamepad. + * + * \param type the type of gamepad to check. + * \param button a button index (one of the SDL_GamepadButton values). + * \returns the SDL_GamepadButtonLabel enum corresponding to the button label. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadButtonLabel + } +function SDL_GetGamepadButtonLabelForType(type_: TSDL_GamepadType; button: TSDL_GamepadButton): TSDL_GamepadButtonLabel; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadButtonLabelForType' {$ENDIF} {$ENDIF}; + +{* + * Get the label of a button on a gamepad. + * + * \param gamepad a gamepad. + * \param button a button index (one of the SDL_GamepadButton values). + * \returns the SDL_GamepadButtonLabel enum corresponding to the button label. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadButtonLabelForType + } +function SDL_GetGamepadButtonLabel(gamepad: PSDL_Gamepad; button: TSDL_GamepadButton): TSDL_GamepadButtonLabel; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadButtonLabel' {$ENDIF} {$ENDIF}; + +{* + * Get the number of touchpads on a gamepad. + * + * \param gamepad a gamepad. + * \returns number of touchpads. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumGamepadTouchpadFingers + } +function SDL_GetNumGamepadTouchpads(gamepad: PSDL_Gamepad): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetNumGamepadTouchpads' {$ENDIF} {$ENDIF}; + +{* + * Get the number of supported simultaneous fingers on a touchpad on a game + * gamepad. + * + * \param gamepad a gamepad. + * \param touchpad a touchpad. + * \returns number of supported simultaneous fingers. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadTouchpadFinger + * \sa SDL_GetNumGamepadTouchpads + } +function SDL_GetNumGamepadTouchpadFingers(gamepad: PSDL_Gamepad; touchpad: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetNumGamepadTouchpadFingers' {$ENDIF} {$ENDIF}; + +{* + * Get the current state of a finger on a touchpad on a gamepad. + * + * \param gamepad a gamepad. + * \param touchpad a touchpad. + * \param finger a finger. + * \param down a Pointer filled with true if the finger is down, false + * otherwise, may be nil. + * \param x a Pointer filled with the x position, normalized 0 to 1, with the + * origin in the upper left, may be nil. + * \param y a Pointer filled with the y position, normalized 0 to 1, with the + * origin in the upper left, may be nil. + * \param pressure a Pointer filled with pressure value, may be nil. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumGamepadTouchpadFingers + } +function SDL_GetGamepadTouchpadFinger(gamepad: PSDL_Gamepad; touchpad: cint; finger: cint; down: pcbool; x: pcfloat; y: pcfloat; pressure: pcfloat): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadTouchpadFinger' {$ENDIF} {$ENDIF}; + +{* + * Return whether a gamepad has a particular sensor. + * + * \param gamepad the gamepad to query. + * \param type the type of sensor to query. + * \returns true if the sensor exists, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadSensorData + * \sa SDL_GetGamepadSensorDataRate + * \sa SDL_SetGamepadSensorEnabled + } +function SDL_GamepadHasSensor(gamepad: PSDL_Gamepad; type_: TSDL_SensorType): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GamepadHasSensor' {$ENDIF} {$ENDIF}; + +{* + * Set whether data reporting for a gamepad sensor is enabled. + * + * \param gamepad the gamepad to update. + * \param type the type of sensor to enable/disable. + * \param enabled whether data reporting should be enabled. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GamepadHasSensor + * \sa SDL_GamepadSensorEnabled + } +function SDL_SetGamepadSensorEnabled(gamepad: PSDL_Gamepad; type_: TSDL_SensorType; enabled: cbool): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetGamepadSensorEnabled' {$ENDIF} {$ENDIF}; + +{* + * Query whether sensor data reporting is enabled for a gamepad. + * + * \param gamepad the gamepad to query. + * \param type the type of sensor to query. + * \returns true if the sensor is enabled, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetGamepadSensorEnabled + } +function SDL_GamepadSensorEnabled(gamepad: PSDL_Gamepad; type_: TSDL_SensorType): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GamepadSensorEnabled' {$ENDIF} {$ENDIF}; + +{* + * Get the data rate (number of events per second) of a gamepad sensor. + * + * \param gamepad the gamepad to query. + * \param type the type of sensor to query. + * \returns the data rate, or 0.0f if the data rate is not available. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetGamepadSensorDataRate(gamepad: PSDL_Gamepad; type_: TSDL_SensorType): cfloat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadSensorDataRate' {$ENDIF} {$ENDIF}; + +{* + * Get the current state of a gamepad sensor. + * + * The number of values and interpretation of the data is sensor dependent. + * See SDL_sensor.h for the details for each type of sensor. + * + * \param gamepad the gamepad to query. + * \param type the type of sensor to query. + * \param data a Pointer filled with the current sensor state. + * \param num_values the number of values to write to data. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetGamepadSensorData(gamepad: PSDL_Gamepad; type_: TSDL_SensorType; data: pcfloat; num_values: cint): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadSensorData' {$ENDIF} {$ENDIF}; + +{* + * Start a rumble effect on a gamepad. + * + * Each call to this function cancels any previous rumble effect, and calling + * it with 0 intensity stops any rumbling. + * + * This function requires you to process SDL events or call + * SDL_UpdateJoysticks() to update rumble state. + * + * \param gamepad the gamepad to vibrate. + * \param low_frequency_rumble the intensity of the low frequency (left) + * rumble motor, from 0 to 0xFFFF. + * \param high_frequency_rumble the intensity of the high frequency (right) + * rumble motor, from 0 to 0xFFFF. + * \param duration_ms the duration of the rumble effect, in milliseconds. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_RumbleGamepad(gamepad: PSDL_Gamepad; low_frequency_rumble: cuint16; high_frequency_rumble: cuint16; duration_ms: cuint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RumbleGamepad' {$ENDIF} {$ENDIF}; + +{* + * Start a rumble effect in the gamepad's triggers. + * + * Each call to this function cancels any previous trigger rumble effect, and + * calling it with 0 intensity stops any rumbling. + * + * Note that this is rumbling of the _triggers_ and not the gamepad as a + * whole. This is currently only supported on Xbox One gamepads. If you want + * the (more common) whole-gamepad rumble, use SDL_RumbleGamepad() instead. + * + * This function requires you to process SDL events or call + * SDL_UpdateJoysticks() to update rumble state. + * + * \param gamepad the gamepad to vibrate. + * \param left_rumble the intensity of the left trigger rumble motor, from 0 + * to 0xFFFF. + * \param right_rumble the intensity of the right trigger rumble motor, from 0 + * to 0xFFFF. + * \param duration_ms the duration of the rumble effect, in milliseconds. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RumbleGamepad + } +function SDL_RumbleGamepadTriggers(gamepad: PSDL_Gamepad; left_rumble: cuint16; right_rumble: cuint16; duration_ms: cuint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RumbleGamepadTriggers' {$ENDIF} {$ENDIF}; + +{* + * Update a gamepad's LED color. + * + * An example of a joystick LED is the light on the back of a PlayStation 4's + * DualShock 4 controller. + * + * For gamepads with a single color LED, the maximum of the RGB values will be + * used as the LED brightness. + * + * \param gamepad the gamepad to update. + * \param red the intensity of the red LED. + * \param green the intensity of the green LED. + * \param blue the intensity of the blue LED. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_SetGamepadLED(gamepad: PSDL_Gamepad; red: cuint8; green: cuint8; blue: cuint8): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetGamepadLED' {$ENDIF} {$ENDIF}; + +{* + * Send a gamepad specific effect packet. + * + * \param gamepad the gamepad to affect. + * \param data the data to send to the gamepad. + * \param size the size of the data to send to the gamepad. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_SendGamepadEffect(gamepad: PSDL_Gamepad; data: Pointer; size: cint): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SendGamepadEffect' {$ENDIF} {$ENDIF}; + +{* + * Close a gamepad previously opened with SDL_OpenGamepad(). + * + * \param gamepad a gamepad identifier previously returned by + * SDL_OpenGamepad(). + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenGamepad + } +procedure SDL_CloseGamepad(gamepad: PSDL_Gamepad); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CloseGamepad' {$ENDIF} {$ENDIF}; + +{* + * Return the sfSymbolsName for a given button on a gamepad on Apple + * platforms. + * + * \param gamepad the gamepad to query. + * \param button a button on the gamepad. + * \returns the sfSymbolsName or nil if the name can't be found. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadAppleSFSymbolsNameForAxis + } +function SDL_GetGamepadAppleSFSymbolsNameForButton(gamepad: PSDL_Gamepad; button: TSDL_GamepadButton): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadAppleSFSymbolsNameForButton' {$ENDIF} {$ENDIF}; + +{* + * Return the sfSymbolsName for a given axis on a gamepad on Apple platforms. + * + * \param gamepad the gamepad to query. + * \param axis an axis on the gamepad. + * \returns the sfSymbolsName or nil if the name can't be found. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGamepadAppleSFSymbolsNameForButton + } + +function SDL_GetGamepadAppleSFSymbolsNameForAxis(gamepad: PSDL_Gamepad; axis: TSDL_GamepadAxis): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGamepadAppleSFSymbolsNameForAxis' {$ENDIF} {$ENDIF}; From d3b472a7bff7204ec0619ee3f58916f8d3289450 Mon Sep 17 00:00:00 2001 From: Matthias Date: Wed, 5 Feb 2025 23:16:04 +0100 Subject: [PATCH 02/18] Add SDL_gpu.inc --- units/SDL3.pas | 1 + units/SDL_gpu.inc | 4097 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 4098 insertions(+) create mode 100644 units/SDL_gpu.inc diff --git a/units/SDL3.pas b/units/SDL3.pas index 52b2857..bdae772 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -104,6 +104,7 @@ interface {$I SDL_camera.inc} // 3.1.6-prev {$I SDL_events.inc} // 3.1.6-prev {$I SDL_render.inc} // 3.1.6-prev +{$I SDL_gpu.inc} // 3.2.0 {$I SDL_clipboard.inc} // 3.2.0 {$I SDL_cpuinfo.inc} // 3.2.0 {$I SDL_dialog.inc} // 3.2.0 diff --git a/units/SDL_gpu.inc b/units/SDL_gpu.inc new file mode 100644 index 0000000..11ff3c3 --- /dev/null +++ b/units/SDL_gpu.inc @@ -0,0 +1,4097 @@ +{ + This file is part of: + + SDL3 for Pascal + (https://github.com/PascalGameDevelopment/SDL3-for-Pascal) + SPDX-License-Identifier: Zlib +} + +{* + * # 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_WaitAndAcquireGPUSwapchainTexture() to render to the window. + * + * Rendering actually happens in a Render Pass, which is encoded into a + * command buffer. One can encode multiple render passes (or alternate between + * render and compute passes) in a single command buffer, but many apps might + * simply need a single render pass in a single command buffer. Render Passes + * can render to up to four color textures and one depth texture + * simultaneously. If the set of textures being rendered to needs to change, + * the Render Pass must be ended and a new one must be begun. + * + * The app calls SDL_BeginGPURenderPass(). Then it sets states it needs for + * each draw: + * + * - SDL_BindGPUGraphicsPipeline() + * - SDL_SetGPUViewport() + * - SDL_BindGPUVertexBuffers() + * - SDL_BindGPUVertexSamplers() + * - etc + * + * Then, make the actual draw commands with these states: + * + * - SDL_DrawGPUPrimitives() + * - SDL_DrawGPUPrimitivesIndirect() + * - SDL_DrawGPUIndexedPrimitivesIndirect() + * - etc + * + * After all the drawing commands for a pass are complete, the app should call + * SDL_EndGPURenderPass(). Once a render pass ends all render-related state is + * reset. + * + * The app can begin new Render Passes and make new draws in the same command + * buffer until the entire scene is rendered. + * + * Once all of the render commands for the scene are complete, the app calls + * SDL_SubmitGPUCommandBuffer() to send it to the GPU for processing. + * + * If the app needs to read back data from texture or buffers, the API has an + * efficient way of doing this, provided that the app is willing to tolerate + * some latency. When the app uses SDL_DownloadFromGPUTexture() or + * SDL_DownloadFromGPUBuffer(), submitting the command buffer with + * SDL_SubmitGPUCommandBufferAndAcquireFence() will return a fence handle that + * the app can poll or wait on in a thread. Once the fence indicates that the + * command buffer is done processing, it is safe to read the downloaded data. + * Make sure to call SDL_ReleaseGPUFence() when done with the fence. + * + * The API also has "compute" support. The app calls SDL_BeginGPUComputePass() + * with compute-writeable textures and/or buffers, which can be written to in + * a compute shader. Then it sets states it needs for the compute dispatches: + * + * - SDL_BindGPUComputePipeline() + * - SDL_BindGPUComputeStorageBuffers() + * - SDL_BindGPUComputeStorageTextures() + * + * Then, dispatch compute work: + * + * - SDL_DispatchGPUCompute() + * + * For advanced users, this opens up powerful GPU-driven workflows. + * + * Graphics and compute pipelines require the use of shaders, which as + * mentioned above are small programs executed on the GPU. Each backend + * (Vulkan, Metal, D3D12) requires a different shader format. When the app + * creates the GPU device, the app lets the device know which shader formats + * the app can provide. It will then select the appropriate backend depending + * on the available shader formats and the backends available on the platform. + * When creating shaders, the app must provide the correct shader format for + * the selected backend. If you would like to learn more about why the API + * works this way, there is a detailed + * [blog post](https://moonside.games/posts/layers-all-the-way-down/) + * explaining this situation. + * + * It is optimal for apps to pre-compile the shader formats they might use, + * but for ease of use SDL provides a separate project, + * [SDL_shadercross](https://github.com/libsdl-org/SDL_shadercross) + * , for performing runtime shader cross-compilation. + * + * This is an extremely quick overview that leaves out several important + * details. Already, though, one can see that GPU programming can be quite + * complex! If you just need simple 2D graphics, the + * [Render API](https://wiki.libsdl.org/SDL3/CategoryRender) + * is much easier to use but still hardware-accelerated. That said, even for + * 2D applications the performance benefits and expressiveness of the GPU API + * are significant. + * + * The GPU API targets a feature set with a wide range of hardware support and + * ease of portability. It is designed so that the app won't have to branch + * itself by querying feature support. If you need cutting-edge features with + * limited hardware support, this API is probably not for you. + * + * Examples demonstrating proper usage of this API can be found + * [here](https://github.com/TheSpydog/SDL_gpu_examples) + * . + * + * ## Performance considerations + * + * Here are some basic tips for maximizing your rendering performance. + * + * - Beginning a new render pass is relatively expensive. Use as few render + * passes as you can. + * - Minimize the amount of state changes. For example, binding a pipeline is + * relatively cheap, but doing it hundreds of times when you don't need to + * will slow the performance significantly. + * - Perform your data uploads as early as possible in the frame. + * - Don't churn resources. Creating and releasing resources is expensive. + * It's better to create what you need up front and cache it. + * - Don't use uniform buffers for large amounts of data (more than a matrix + * or so). Use a storage buffer instead. + * - Use cycling correctly. There is a detailed explanation of cycling further + * below. + * - Use culling techniques to minimize pixel writes. The less writing the GPU + * has to do the better. Culling can be a very advanced topic but even + * simple culling techniques can boost performance significantly. + * + * In general try to remember the golden rule of performance: doing things is + * more expensive than not doing things. Don't Touch The Driver! + * + * ## FAQ + * + * **Question: When are you adding more advanced features, like ray tracing or + * mesh shaders?** + * + * Answer: We don't have immediate plans to add more bleeding-edge features, + * but we certainly might in the future, when these features prove worthwhile, + * and reasonable to implement across several platforms and underlying APIs. + * So while these things are not in the "never" category, they are definitely + * not "near future" items either. + * + * **Question: Why is my shader not working?** + * + * Answer: A common oversight when using shaders is not properly laying out + * the shader resources/registers correctly. The GPU API is very strict with + * how it wants resources to be laid out and it's difficult for the API to + * automatically validate shaders to see if they have a compatible layout. See + * the documentation for SDL_CreateGPUShader() and + * SDL_CreateGPUComputePipeline() for information on the expected layout. + * + * Another common issue is not setting the correct number of samplers, + * textures, and buffers in SDL_GPUShaderCreateInfo. If possible use shader + * reflection to extract the required information from the shader + * automatically instead of manually filling in the struct's values. + * + * **Question: My application isn't performing very well. Is this the GPU + * API's fault?** + * + * Answer: No. Long answer: The GPU API is a relatively thin layer over the + * underlying graphics API. While it's possible that we have done something + * inefficiently, it's very unlikely especially if you are relatively + * inexperienced with GPU rendering. Please see the performance tips above and + * make sure you are following them. Additionally, tools like RenderDoc can be + * very helpful for diagnosing incorrect behavior and performance issues. + * + * ## System Requirements + * + * **Vulkan:** Supported on Windows, Linux, Nintendo Switch, and certain + * Android devices. Requires Vulkan 1.0 with the following extensions and + * device features: + * + * - `VK_KHR_swapchain` + * - `VK_KHR_maintenance1` + * - `independentBlend` + * - `imageCubeArray` + * - `depthClamp` + * - `shaderClipDistance` + * - `drawIndirectFirstInstance` + * + * **D3D12:** Supported on Windows 10 or newer, Xbox One (GDK), and Xbox + * Series X|S (GDK). Requires a GPU that supports DirectX 12 Feature Level + * 11_1. + * + * **Metal:** Supported on macOS 10.14+ and iOS/tvOS 13.0+. Hardware + * requirements vary by operating system: + * + * - macOS requires an Apple Silicon or + * [Intel Mac2 family](https://developer.apple.com/documentation/metal/mtlfeatureset/mtlfeatureset_macos_gpufamily2_v1?language=objc) + * GPU + * - iOS/tvOS requires an A9 GPU or newer + * - iOS Simulator and tvOS Simulator are unsupported + * + * ## Uniform Data + * + * Uniforms are for passing data to shaders. The uniform data will be constant + * across all executions of the shader. + * + * There are 4 available uniform slots per shader stage (where the stages are + * vertex, fragment, and compute). Uniform data pushed to a slot on a stage + * keeps its value throughout the command buffer until you call the relevant + * Push function on that slot again. + * + * For example, you could write your vertex shaders to read a camera matrix + * from uniform binding slot 0, push the camera matrix at the start of the + * command buffer, and that data will be used for every subsequent draw call. + * + * It is valid to push uniform data during a render or compute pass. + * + * Uniforms are best for pushing small amounts of data. If you are pushing + * more than a matrix or two per call you should consider using a storage + * buffer instead. + * + * ## A Note On Cycling + * + * When using a command buffer, operations do not occur immediately - they + * occur some time after the command buffer is submitted. + * + * When a resource is used in a pending or active command buffer, it is + * considered to be "bound". When a resource is no longer used in any pending + * or active command buffers, it is considered to be "unbound". + * + * If data resources are bound, it is unspecified when that data will be + * unbound unless you acquire a fence when submitting the command buffer and + * wait on it. However, this doesn't mean you need to track resource usage + * manually. + * + * All of the functions and structs that involve writing to a resource have a + * "cycle" bool. SDL_GPUTransferBuffer, SDL_GPUBuffer, and SDL_GPUTexture all + * effectively function as ring buffers on internal resources. When cycle is + * true, if the resource is bound, the cycle rotates to the next unbound + * internal resource, or if none are available, a new one is created. This + * means you don't have to worry about complex state tracking and + * synchronization as long as cycling is correctly employed. + * + * For example: you can call SDL_MapGPUTransferBuffer(), write texture data, + * SDL_UnmapGPUTransferBuffer(), and then SDL_UploadToGPUTexture(). The next + * time you write texture data to the transfer buffer, if you set the cycle + * param to true, you don't have to worry about overwriting any data that is + * not yet uploaded. + * + * Another example: If you are using a texture in a render pass every frame, + * this can cause a data dependency between frames. If you set cycle to true + * in the SDL_GPUColorTargetInfo struct, you can prevent this data dependency. + * + * Cycling will never undefine already bound data. When cycling, all data in + * the resource is considered to be undefined for subsequent commands until + * that data is written again. You must take care not to read undefined data. + * + * Note that when cycling a texture, the entire texture will be cycled, even + * if only part of the texture is used in the call, so you must consider the + * entire texture to contain undefined data after cycling. + * + * You must also take care not to overwrite a section of data that has been + * referenced in a command without cycling first. It is OK to overwrite + * unreferenced data in a bound resource without cycling, but overwriting a + * section of data that has already been referenced will produce unexpected + * results. + } + +{ Type Declarations } + +{* + * An opaque handle representing the SDL_GPU context. + * + * \since This struct is available since SDL 3.2.0. + } +type + PPSDL_GPUDevice = ^PSDL_GPUDevice; + PSDL_GPUDevice = type Pointer; + +{* + * An opaque handle representing a buffer. + * + * Used for vertices, indices, indirect draw commands, and general compute + * data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_CopyGPUBufferToBuffer + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + * \sa SDL_BindGPUVertexStorageBuffers + * \sa SDL_BindGPUFragmentStorageBuffers + * \sa SDL_DrawGPUPrimitivesIndirect + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + * \sa SDL_BindGPUComputeStorageBuffers + * \sa SDL_DispatchGPUComputeIndirect + * \sa SDL_ReleaseGPUBuffer + } +type + PPSDL_GPUBuffer = ^PSDL_GPUBuffer; + PSDL_GPUBuffer = type Pointer; + +{* + * An opaque handle representing a transfer buffer. + * + * Used for transferring data to and from the device. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + * \sa SDL_MapGPUTransferBuffer + * \sa SDL_UnmapGPUTransferBuffer + * \sa SDL_UploadToGPUBuffer + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_ReleaseGPUTransferBuffer + } +type + PPSDL_GPUTransferBuffer = ^PSDL_GPUTransferBuffer; + PSDL_GPUTransferBuffer = type Pointer; + +{* + * An opaque handle representing a texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_CopyGPUTextureToTexture + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUVertexStorageTextures + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_BindGPUFragmentStorageTextures + * \sa SDL_BindGPUComputeStorageTextures + * \sa SDL_GenerateMipmapsForGPUTexture + * \sa SDL_BlitGPUTexture + * \sa SDL_ReleaseGPUTexture + } +type + PPSDL_GPUTexture = ^PSDL_GPUTexture; + PSDL_GPUTexture = type Pointer; + +{* + * An opaque handle representing a sampler. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_ReleaseGPUSampler + } +type + PPSDL_GPUSampler = ^PSDL_GPUSampler; + PSDL_GPUSampler = type Pointer; + +{* + * An opaque handle representing a compiled shader object. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_ReleaseGPUShader + } +type + PPSDL_GPUShader = ^PSDL_GPUShader; + PSDL_GPUShader = type Pointer; + +{* + * An opaque handle representing a compute pipeline. + * + * Used during compute passes. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUComputePipeline + * \sa SDL_BindGPUComputePipeline + * \sa SDL_ReleaseGPUComputePipeline + } +type + PPSDL_GPUComputePipeline = ^PSDL_GPUComputePipeline; + PSDL_GPUComputePipeline = type Pointer; + +{* + * An opaque handle representing a graphics pipeline. + * + * Used during render passes. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_BindGPUGraphicsPipeline + * \sa SDL_ReleaseGPUGraphicsPipeline + } +type + PPSDL_GPUGraphicsPipeline = ^PSDL_GPUGraphicsPipeline; + PSDL_GPUGraphicsPipeline = type Pointer; + +{* + * An opaque handle representing a command buffer. + * + * Most state is managed via command buffers. When setting state using a + * command buffer, that state is local to the command buffer. + * + * Commands only begin execution on the GPU once SDL_SubmitGPUCommandBuffer is + * called. Once the command buffer is submitted, it is no longer valid to use + * it. + * + * Command buffers are executed in submission order. If you submit command + * buffer A and then command buffer B all commands in A will begin executing + * before any command in B begins executing. + * + * In multi-threading scenarios, you should only access a command buffer on + * the thread you acquired it from. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + } +type + PPSDL_GPUCommandBuffer = ^PSDL_GPUCommandBuffer; + PSDL_GPUCommandBuffer = type Pointer; + +{* + * An opaque handle representing a render pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPURenderPass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + * \sa SDL_EndGPURenderPass + } +type + PPSDL_GPURenderPass = ^PSDL_GPURenderPass; + PSDL_GPURenderPass = type Pointer; + +{* + * An opaque handle representing a compute pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPUComputePass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + * \sa SDL_EndGPUComputePass + } +type + PPSDL_GPUComputePass = ^PSDL_GPUComputePass; + PSDL_GPUComputePass = type Pointer; + +{* + * An opaque handle representing a copy pass. + * + * This handle is transient and should not be held or referenced after + * SDL_EndGPUCopyPass is called. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUCopyPass + * \sa SDL_EndGPUCopyPass + } +type + PPSDL_GPUCopyPass = ^PSDL_GPUCopyPass; + PSDL_GPUCopyPass = type Pointer; + +{* + * An opaque handle representing a fence. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_QueryGPUFence + * \sa SDL_WaitForGPUFences + * \sa SDL_ReleaseGPUFence + } +type + PPSDL_GPUFence = ^PSDL_GPUFence; + PSDL_GPUFence = type Pointer; + +{* + * Specifies the primitive topology of a graphics pipeline. + * + * If you are using POINTLIST you must include a point size output in the + * vertex shader. + * + * - For HLSL compiling to SPIRV you must decorate a float output with + * [[vk:: builtin("PointSize")]]. + * - For GLSL you must set the gl_PointSize builtin. + * - For MSL you must include a float output with the [[point_size]] + * decorator. + * + * Note that sized point topology is totally unsupported on D3D12. Any size + * other than 1 will be ignored. In general, you should avoid using point + * topology for both compatibility and performance reasons. You WILL regret + * using it. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + } +type + PPSDL_GPUPrimitiveType = ^PSDL_GPUPrimitiveType; + PSDL_GPUPrimitiveType = ^TSDL_GPUPrimitiveType; + TSDL_GPUPrimitiveType = type Integer; +const + SDL_GPU_PRIMITIVETYPE_TRIANGLELIST = TSDL_GPUPrimitiveType(0); {*< A series of separate triangles. } + SDL_GPU_PRIMITIVETYPE_TRIANGLESTRIP = TSDL_GPUPrimitiveType(1); {*< A series of connected triangles. } + SDL_GPU_PRIMITIVETYPE_LINELIST = TSDL_GPUPrimitiveType(2); {*< A series of separate lines. } + SDL_GPU_PRIMITIVETYPE_LINESTRIP = TSDL_GPUPrimitiveType(3); {*< A series of connected lines. } + SDL_GPU_PRIMITIVETYPE_POINTLIST = TSDL_GPUPrimitiveType(4); {*< A series of separate points. } + +{* + * Specifies how the contents of a texture attached to a render pass are + * treated at the beginning of the render pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + } +type + PPSDL_GPULoadOp = ^PSDL_GPULoadOp; + PSDL_GPULoadOp = ^TSDL_GPULoadOp; + TSDL_GPULoadOp = type Integer; +const + SDL_GPU_LOADOP_LOAD = TSDL_GPULoadOp(0); {*< The previous contents of the texture will be preserved. } + SDL_GPU_LOADOP_CLEAR = TSDL_GPULoadOp(1); {*< The contents of the texture will be cleared to a color. } + SDL_GPU_LOADOP_DONT_CARE = TSDL_GPULoadOp(2); {*< The previous contents of the texture need not be preserved. The contents will be undefined. } + +{* + * Specifies how the contents of a texture attached to a render pass are + * treated at the end of the render pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + } +type + PPSDL_GPUStoreOp = ^PSDL_GPUStoreOp; + PSDL_GPUStoreOp = ^TSDL_GPUStoreOp; + TSDL_GPUStoreOp = type Integer; +const + SDL_GPU_STOREOP_STORE = TSDL_GPUStoreOp(0); {*< The contents generated during the render pass will be written to memory. } + SDL_GPU_STOREOP_DONT_CARE = TSDL_GPUStoreOp(1); {*< The contents generated during the render pass are not needed and may be discarded. The contents will be undefined. } + SDL_GPU_STOREOP_RESOLVE = TSDL_GPUStoreOp(2); {*< 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 = TSDL_GPUStoreOp(3); {*< The multisample contents generated during the render pass will be resolved to a non-multisample texture. The contents in the multisample texture will be written to memory. } + +{* + * Specifies the size of elements in an index buffer. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + } +type + PPSDL_GPUIndexElementSize = ^PSDL_GPUIndexElementSize; + PSDL_GPUIndexElementSize = ^TSDL_GPUIndexElementSize; + TSDL_GPUIndexElementSize = type Integer; +const + SDL_GPU_INDEXELEMENTSIZE_16BIT = TSDL_GPUIndexElementSize(0); {*< The index elements are 16-bit. } + SDL_GPU_INDEXELEMENTSIZE_32BIT = TSDL_GPUIndexElementSize(1); {*< The index elements are 32-bit. } + +{* + * Specifies the pixel format of a texture. + * + * Texture format support varies depending on driver, hardware, and usage + * flags. In general, you should use SDL_GPUTextureSupportsFormat to query if + * a format is supported before using it. However, there are a few guaranteed + * formats. + * + * FIXME: Check universal support for 32-bit component formats FIXME: Check + * universal support for SIMULTANEOUS_READ_WRITE + * + * For SAMPLER usage, the following formats are universally supported: + * + * - R8G8B8A8_UNORM + * - B8G8R8A8_UNORM + * - R8_UNORM + * - R8_SNORM + * - R8G8_UNORM + * - R8G8_SNORM + * - R8G8B8A8_SNORM + * - R16_FLOAT + * - R16G16_FLOAT + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R11G11B10_UFLOAT + * - R8G8B8A8_UNORM_SRGB + * - B8G8R8A8_UNORM_SRGB + * - D16_UNORM + * + * For COLOR_TARGET usage, the following formats are universally supported: + * + * - R8G8B8A8_UNORM + * - B8G8R8A8_UNORM + * - R8_UNORM + * - R16_FLOAT + * - R16G16_FLOAT + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R8_UINT + * - R8G8_UINT + * - R8G8B8A8_UINT + * - R16_UINT + * - R16G16_UINT + * - R16G16B16A16_UINT + * - R8_INT + * - R8G8_INT + * - R8G8B8A8_INT + * - R16_INT + * - R16G16_INT + * - R16G16B16A16_INT + * - R8G8B8A8_UNORM_SRGB + * - B8G8R8A8_UNORM_SRGB + * + * For STORAGE usages, the following formats are universally supported: + * + * - R8G8B8A8_UNORM + * - R8G8B8A8_SNORM + * - R16G16B16A16_FLOAT + * - R32_FLOAT + * - R32G32_FLOAT + * - R32G32B32A32_FLOAT + * - R8G8B8A8_UINT + * - R16G16B16A16_UINT + * - R8G8B8A8_INT + * - R16G16B16A16_INT + * + * For DEPTH_STENCIL_TARGET usage, the following formats are universally + * supported: + * + * - D16_UNORM + * - Either (but not necessarily both!) D24_UNORM or D32_FLOAT + * - Either (but not necessarily both!) D24_UNORM_S8_UINT or D32_FLOAT_S8_UINT + * + * Unless D16_UNORM is sufficient for your purposes, always check which of + * D24/D32 is supported before creating a depth-stencil texture! + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureSupportsFormat + } +type + PPSDL_GPUTextureFormat = ^PSDL_GPUTextureFormat; + PSDL_GPUTextureFormat = ^TSDL_GPUTextureFormat; + TSDL_GPUTextureFormat = type Integer; +const + SDL_GPU_TEXTUREFORMAT_INVALID = TSDL_GPUTextureFormat(0); + + { Unsigned Normalized Float Color Formats } + SDL_GPU_TEXTUREFORMAT_A8_UNORM = TSDL_GPUTextureFormat(1); + SDL_GPU_TEXTUREFORMAT_R8_UNORM = TSDL_GPUTextureFormat(2); + SDL_GPU_TEXTUREFORMAT_R8G8_UNORM = TSDL_GPUTextureFormat(3); + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM = TSDL_GPUTextureFormat(4); + SDL_GPU_TEXTUREFORMAT_R16_UNORM = TSDL_GPUTextureFormat(5); + SDL_GPU_TEXTUREFORMAT_R16G16_UNORM = TSDL_GPUTextureFormat(6); + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UNORM = TSDL_GPUTextureFormat(7); + SDL_GPU_TEXTUREFORMAT_R10G10B10A2_UNORM = TSDL_GPUTextureFormat(8); + SDL_GPU_TEXTUREFORMAT_B5G6R5_UNORM = TSDL_GPUTextureFormat(9); + SDL_GPU_TEXTUREFORMAT_B5G5R5A1_UNORM = TSDL_GPUTextureFormat(10); + SDL_GPU_TEXTUREFORMAT_B4G4R4A4_UNORM = TSDL_GPUTextureFormat(11); + SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM = TSDL_GPUTextureFormat(12); + { Compressed Unsigned Normalized Float Color Formats } + SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM = TSDL_GPUTextureFormat(13); + SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM = TSDL_GPUTextureFormat(14); + SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM = TSDL_GPUTextureFormat(15); + SDL_GPU_TEXTUREFORMAT_BC4_R_UNORM = TSDL_GPUTextureFormat(16); + SDL_GPU_TEXTUREFORMAT_BC5_RG_UNORM = TSDL_GPUTextureFormat(17); + SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM = TSDL_GPUTextureFormat(18); + { Compressed Signed Float Color Formats } + SDL_GPU_TEXTUREFORMAT_BC6H_RGB_FLOAT = TSDL_GPUTextureFormat(19); + { Compressed Unsigned Float Color Formats } + SDL_GPU_TEXTUREFORMAT_BC6H_RGB_UFLOAT = TSDL_GPUTextureFormat(20); + { Signed Normalized Float Color Formats } + SDL_GPU_TEXTUREFORMAT_R8_SNORM = TSDL_GPUTextureFormat(21); + SDL_GPU_TEXTUREFORMAT_R8G8_SNORM = TSDL_GPUTextureFormat(22); + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_SNORM = TSDL_GPUTextureFormat(23); + SDL_GPU_TEXTUREFORMAT_R16_SNORM = TSDL_GPUTextureFormat(24); + SDL_GPU_TEXTUREFORMAT_R16G16_SNORM = TSDL_GPUTextureFormat(25); + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_SNORM = TSDL_GPUTextureFormat(26); + { Signed Float Color Formats } + SDL_GPU_TEXTUREFORMAT_R16_FLOAT = TSDL_GPUTextureFormat(27); + SDL_GPU_TEXTUREFORMAT_R16G16_FLOAT = TSDL_GPUTextureFormat(28); + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_FLOAT = TSDL_GPUTextureFormat(29); + SDL_GPU_TEXTUREFORMAT_R32_FLOAT = TSDL_GPUTextureFormat(30); + SDL_GPU_TEXTUREFORMAT_R32G32_FLOAT = TSDL_GPUTextureFormat(31); + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_FLOAT = TSDL_GPUTextureFormat(32); + { Unsigned Float Color Formats } + SDL_GPU_TEXTUREFORMAT_R11G11B10_UFLOAT = TSDL_GPUTextureFormat(33); + { Unsigned Integer Color Formats } + SDL_GPU_TEXTUREFORMAT_R8_UINT = TSDL_GPUTextureFormat(34); + SDL_GPU_TEXTUREFORMAT_R8G8_UINT = TSDL_GPUTextureFormat(35); + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UINT = TSDL_GPUTextureFormat(36); + SDL_GPU_TEXTUREFORMAT_R16_UINT = TSDL_GPUTextureFormat(37); + SDL_GPU_TEXTUREFORMAT_R16G16_UINT = TSDL_GPUTextureFormat(38); + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_UINT = TSDL_GPUTextureFormat(39); + SDL_GPU_TEXTUREFORMAT_R32_UINT = TSDL_GPUTextureFormat(40); + SDL_GPU_TEXTUREFORMAT_R32G32_UINT = TSDL_GPUTextureFormat(41); + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_UINT = TSDL_GPUTextureFormat(42); + { Signed Integer Color Formats } + SDL_GPU_TEXTUREFORMAT_R8_INT = TSDL_GPUTextureFormat(43); + SDL_GPU_TEXTUREFORMAT_R8G8_INT = TSDL_GPUTextureFormat(44); + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_INT = TSDL_GPUTextureFormat(45); + SDL_GPU_TEXTUREFORMAT_R16_INT = TSDL_GPUTextureFormat(46); + SDL_GPU_TEXTUREFORMAT_R16G16_INT = TSDL_GPUTextureFormat(47); + SDL_GPU_TEXTUREFORMAT_R16G16B16A16_INT = TSDL_GPUTextureFormat(48); + SDL_GPU_TEXTUREFORMAT_R32_INT = TSDL_GPUTextureFormat(49); + SDL_GPU_TEXTUREFORMAT_R32G32_INT = TSDL_GPUTextureFormat(50); + SDL_GPU_TEXTUREFORMAT_R32G32B32A32_INT = TSDL_GPUTextureFormat(51); + { SRGB Unsigned Normalized Color Formats } + SDL_GPU_TEXTUREFORMAT_R8G8B8A8_UNORM_SRGB = TSDL_GPUTextureFormat(52); + SDL_GPU_TEXTUREFORMAT_B8G8R8A8_UNORM_SRGB = TSDL_GPUTextureFormat(53); + { Compressed SRGB Unsigned Normalized Color Formats } + SDL_GPU_TEXTUREFORMAT_BC1_RGBA_UNORM_SRGB = TSDL_GPUTextureFormat(54); + SDL_GPU_TEXTUREFORMAT_BC2_RGBA_UNORM_SRGB = TSDL_GPUTextureFormat(55); + SDL_GPU_TEXTUREFORMAT_BC3_RGBA_UNORM_SRGB = TSDL_GPUTextureFormat(56); + SDL_GPU_TEXTUREFORMAT_BC7_RGBA_UNORM_SRGB = TSDL_GPUTextureFormat(57); + { Depth Formats } + SDL_GPU_TEXTUREFORMAT_D16_UNORM = TSDL_GPUTextureFormat(58); + SDL_GPU_TEXTUREFORMAT_D24_UNORM = TSDL_GPUTextureFormat(59); + SDL_GPU_TEXTUREFORMAT_D32_FLOAT = TSDL_GPUTextureFormat(60); + SDL_GPU_TEXTUREFORMAT_D24_UNORM_S8_UINT = TSDL_GPUTextureFormat(61); + SDL_GPU_TEXTUREFORMAT_D32_FLOAT_S8_UINT = TSDL_GPUTextureFormat(62); + { Compressed ASTC Normalized Float Color Formats } + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM = TSDL_GPUTextureFormat(63); + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM = TSDL_GPUTextureFormat(64); + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM = TSDL_GPUTextureFormat(65); + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM = TSDL_GPUTextureFormat(66); + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM = TSDL_GPUTextureFormat(67); + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM = TSDL_GPUTextureFormat(68); + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM = TSDL_GPUTextureFormat(69); + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM = TSDL_GPUTextureFormat(70); + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM = TSDL_GPUTextureFormat(71); + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM = TSDL_GPUTextureFormat(72); + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM = TSDL_GPUTextureFormat(73); + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM = TSDL_GPUTextureFormat(74); + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM = TSDL_GPUTextureFormat(75); + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM = TSDL_GPUTextureFormat(76); + { Compressed SRGB ASTC Normalized Float Color Formats } + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_UNORM_SRGB = TSDL_GPUTextureFormat(77); + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_UNORM_SRGB = TSDL_GPUTextureFormat(78); + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_UNORM_SRGB = TSDL_GPUTextureFormat(79); + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_UNORM_SRGB = TSDL_GPUTextureFormat(80); + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_UNORM_SRGB = TSDL_GPUTextureFormat(81); + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_UNORM_SRGB = TSDL_GPUTextureFormat(82); + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_UNORM_SRGB = TSDL_GPUTextureFormat(83); + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_UNORM_SRGB = TSDL_GPUTextureFormat(84); + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_UNORM_SRGB = TSDL_GPUTextureFormat(85); + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_UNORM_SRGB = TSDL_GPUTextureFormat(86); + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_UNORM_SRGB = TSDL_GPUTextureFormat(87); + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_UNORM_SRGB = TSDL_GPUTextureFormat(88); + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_UNORM_SRGB = TSDL_GPUTextureFormat(89); + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_UNORM_SRGB = TSDL_GPUTextureFormat(90); + { Compressed ASTC Signed Float Color Formats } + SDL_GPU_TEXTUREFORMAT_ASTC_4x4_FLOAT = TSDL_GPUTextureFormat(91); + SDL_GPU_TEXTUREFORMAT_ASTC_5x4_FLOAT = TSDL_GPUTextureFormat(92); + SDL_GPU_TEXTUREFORMAT_ASTC_5x5_FLOAT = TSDL_GPUTextureFormat(93); + SDL_GPU_TEXTUREFORMAT_ASTC_6x5_FLOAT = TSDL_GPUTextureFormat(94); + SDL_GPU_TEXTUREFORMAT_ASTC_6x6_FLOAT = TSDL_GPUTextureFormat(95); + SDL_GPU_TEXTUREFORMAT_ASTC_8x5_FLOAT = TSDL_GPUTextureFormat(96); + SDL_GPU_TEXTUREFORMAT_ASTC_8x6_FLOAT = TSDL_GPUTextureFormat(97); + SDL_GPU_TEXTUREFORMAT_ASTC_8x8_FLOAT = TSDL_GPUTextureFormat(98); + SDL_GPU_TEXTUREFORMAT_ASTC_10x5_FLOAT = TSDL_GPUTextureFormat(99); + SDL_GPU_TEXTUREFORMAT_ASTC_10x6_FLOAT = TSDL_GPUTextureFormat(100); + SDL_GPU_TEXTUREFORMAT_ASTC_10x8_FLOAT = TSDL_GPUTextureFormat(101); + SDL_GPU_TEXTUREFORMAT_ASTC_10x10_FLOAT = TSDL_GPUTextureFormat(102); + SDL_GPU_TEXTUREFORMAT_ASTC_12x10_FLOAT = TSDL_GPUTextureFormat(103); + SDL_GPU_TEXTUREFORMAT_ASTC_12x12_FLOAT = TSDL_GPUTextureFormat(104); + +{* + * Specifies how a texture is intended to be used by the client. + * + * A texture must have at least one usage flag. Note that some usage flag + * combinations are invalid. + * + * With regards to compute storage usage, READ | WRITE means that you can have + * shader A that only writes into the texture and shader B that only reads + * from the texture and bind the same texture to either shader respectively. + * SIMULTANEOUS means that you can do reads and writes within the same shader + * or compute pass. It also implies that atomic ops can be used, since those + * are read-modify-write operations. If you use SIMULTANEOUS, you are + * responsible for avoiding data races, as there is no data synchronization + * within a compute pass. Note that SIMULTANEOUS usage is only supported by a + * limited number of texture formats. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + } +type + PPSDL_GPUTextureUsageFlags = ^PSDL_GPUTextureUsageFlags; + PSDL_GPUTextureUsageFlags = ^TSDL_GPUTextureUsageFlags; + TSDL_GPUTextureUsageFlags = cuint32; +const + SDL_GPU_TEXTUREUSAGE_SAMPLER = 1 shl 0; {*< Texture supports sampling. } + SDL_GPU_TEXTUREUSAGE_COLOR_TARGET = 1 shl 1; {*< Texture is a color render target. } + SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET = 1 shl 2; {*< Texture is a depth stencil target. } + SDL_GPU_TEXTUREUSAGE_GRAPHICS_STORAGE_READ = 1 shl 3; {*< Texture supports storage reads in graphics stages. } + SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_READ = 1 shl 4; {*< Texture supports storage reads in the compute stage. } + SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE = 1 shl 5; {*< Texture supports storage writes in the compute stage. } + SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE = 1 shl 6; {*< Texture supports reads and writes in the same compute shader. This is NOT equivalent to READ | WRITE. } + +{* + * Specifies the type of a texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + } +type + PPSDL_GPUTextureType = ^PSDL_GPUTextureType; + PSDL_GPUTextureType = ^TSDL_GPUTextureType; + TSDL_GPUTextureType = type Integer; +const + SDL_GPU_TEXTURETYPE_2D = TSDL_GPUTextureType(0); {*< The texture is a 2-dimensional image. } + SDL_GPU_TEXTURETYPE_2D_ARRAY = TSDL_GPUTextureType(1); {*< The texture is a 2-dimensional array image. } + SDL_GPU_TEXTURETYPE_3D = TSDL_GPUTextureType(2); {*< The texture is a 3-dimensional image. } + SDL_GPU_TEXTURETYPE_CUBE = TSDL_GPUTextureType(3); {*< The texture is a cube image. } + SDL_GPU_TEXTURETYPE_CUBE_ARRAY = TSDL_GPUTextureType(4); {*< The texture is a cube array image. } + +{* + * Specifies the sample count of a texture. + * + * Used in multisampling. Note that this value only applies when the texture + * is used as a render target. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureSupportsSampleCount + } +type + PPSDL_GPUSampleCount = ^PSDL_GPUSampleCount; + PSDL_GPUSampleCount = ^TSDL_GPUSampleCount; + TSDL_GPUSampleCount = type Integer; +const + SDL_GPU_SAMPLECOUNT_1 = TSDL_GPUSampleCount(0); {*< No multisampling. } + SDL_GPU_SAMPLECOUNT_2 = TSDL_GPUSampleCount(1); {*< MSAA 2x } + SDL_GPU_SAMPLECOUNT_4 = TSDL_GPUSampleCount(2); {*< MSAA 4x } + SDL_GPU_SAMPLECOUNT_8 = TSDL_GPUSampleCount(3); {*< MSAA 8x } + +{* + * Specifies the face of a cube map. + * + * Can be passed in as the layer field in texture-related structs. + * + * \since This enum is available since SDL 3.2.0. + } +type + PPSDL_GPUCubeMapFace = ^PSDL_GPUCubeMapFace; + PSDL_GPUCubeMapFace = ^TSDL_GPUCubeMapFace; + TSDL_GPUCubeMapFace = type Integer; +const + SDL_GPU_CUBEMAPFACE_POSITIVEX = TSDL_GPUCubeMapFace(0); + SDL_GPU_CUBEMAPFACE_NEGATIVEX = TSDL_GPUCubeMapFace(1); + SDL_GPU_CUBEMAPFACE_POSITIVEY = TSDL_GPUCubeMapFace(2); + SDL_GPU_CUBEMAPFACE_NEGATIVEY = TSDL_GPUCubeMapFace(3); + SDL_GPU_CUBEMAPFACE_POSITIVEZ = TSDL_GPUCubeMapFace(4); + SDL_GPU_CUBEMAPFACE_NEGATIVEZ = TSDL_GPUCubeMapFace(5); + +{* + * 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.2.0. + * + * \sa SDL_CreateGPUBuffer + } +type + PPSDL_GPUBufferUsageFlags = ^PSDL_GPUBufferUsageFlags; + PSDL_GPUBufferUsageFlags = ^TSDL_GPUBufferUsageFlags; + TSDL_GPUBufferUsageFlags = type cuint32; +const + SDL_GPU_BUFFERUSAGE_VERTEX = 1 shl 0; {*< Buffer is a vertex buffer. } + SDL_GPU_BUFFERUSAGE_INDEX = 1 shl 1; {*< Buffer is an index buffer. } + SDL_GPU_BUFFERUSAGE_INDIRECT = 1 shl 2; {*< Buffer is an indirect buffer. } + SDL_GPU_BUFFERUSAGE_GRAPHICS_STORAGE_READ = 1 shl 3; {*< Buffer supports storage reads in graphics stages. } + SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_READ = 1 shl 4; {*< Buffer supports storage reads in the compute stage. } + SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE = 1 shl 5; {*< Buffer supports storage writes in the compute stage. } + +{* + * Specifies how a transfer buffer is intended to be used by the client. + * + * Note that mapping and copying FROM an upload transfer buffer or TO a + * download transfer buffer is undefined behavior. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + } +type + PPSDL_GPUTransferBufferUsage = ^PSDL_GPUTransferBufferUsage; + PSDL_GPUTransferBufferUsage = ^TSDL_GPUTransferBufferUsage; + TSDL_GPUTransferBufferUsage = type Integer; +const + SDL_GPU_TRANSFERBUFFERUSAGE_UPLOAD = TSDL_GPUTransferBufferUsage(0); + SDL_GPU_TRANSFERBUFFERUSAGE_DOWNLOAD = TSDL_GPUTransferBufferUsage(1); + +{* + * Specifies which stage a shader program corresponds to. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + } +type + PPSDL_GPUShaderStage = ^PSDL_GPUShaderStage; + PSDL_GPUShaderStage = ^TSDL_GPUShaderStage; + TSDL_GPUShaderStage = type Integer; +const + SDL_GPU_SHADERSTAGE_VERTEX = TSDL_GPUShaderStage(0); + SDL_GPU_SHADERSTAGE_FRAGMENT = TSDL_GPUShaderStage(1); + +{* + * Specifies the format of shader code. + * + * Each format corresponds to a specific backend that accepts it. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + } +type + PPSDL_GPUShaderFormat = ^PSDL_GPUShaderFormat; + PSDL_GPUShaderFormat = ^TSDL_GPUShaderFormat; + TSDL_GPUShaderFormat = type cuint32; +const + SDL_GPU_SHADERFORMAT_INVALID = 0; + SDL_GPU_SHADERFORMAT_PRIVATE = 1 shl 0; {*< Shaders for NDA'd platforms. } + SDL_GPU_SHADERFORMAT_SPIRV = 1 shl 1; {*< SPIR-V shaders for Vulkan. } + SDL_GPU_SHADERFORMAT_DXBC = 1 shl 2; {*< DXBC SM5_1 shaders for D3D12. } + SDL_GPU_SHADERFORMAT_DXIL = 1 shl 3; {*< DXIL SM6_0 shaders for D3D12. } + SDL_GPU_SHADERFORMAT_MSL = 1 shl 4; {*< MSL shaders for Metal. } + SDL_GPU_SHADERFORMAT_METALLIB = 1 shl 5; {*< Precompiled metallib shaders for Metal. } + +{* + * Specifies the format of a vertex attribute. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + } +type + PPSDL_GPUVertexElementFormat = ^PSDL_GPUVertexElementFormat; + PSDL_GPUVertexElementFormat = ^TSDL_GPUVertexElementFormat; + TSDL_GPUVertexElementFormat = type Integer; +const + SDL_GPU_VERTEXELEMENTFORMAT_INVALID = TSDL_GPUVertexElementFormat(0); + + { 32-bit Signed Integers } + SDL_GPU_VERTEXELEMENTFORMAT_INT = TSDL_GPUVertexElementFormat(1); + SDL_GPU_VERTEXELEMENTFORMAT_INT2 = TSDL_GPUVertexElementFormat(2); + SDL_GPU_VERTEXELEMENTFORMAT_INT3 = TSDL_GPUVertexElementFormat(3); + SDL_GPU_VERTEXELEMENTFORMAT_INT4 = TSDL_GPUVertexElementFormat(4); + + { 32-bit Unsigned Integers } + SDL_GPU_VERTEXELEMENTFORMAT_UINT = TSDL_GPUVertexElementFormat(5); + SDL_GPU_VERTEXELEMENTFORMAT_UINT2 = TSDL_GPUVertexElementFormat(6); + SDL_GPU_VERTEXELEMENTFORMAT_UINT3 = TSDL_GPUVertexElementFormat(7); + SDL_GPU_VERTEXELEMENTFORMAT_UINT4 = TSDL_GPUVertexElementFormat(8); + + { 32-bit Floats } + SDL_GPU_VERTEXELEMENTFORMAT_FLOAT = TSDL_GPUVertexElementFormat(9); + SDL_GPU_VERTEXELEMENTFORMAT_FLOAT2 = TSDL_GPUVertexElementFormat(10); + SDL_GPU_VERTEXELEMENTFORMAT_FLOAT3 = TSDL_GPUVertexElementFormat(11); + SDL_GPU_VERTEXELEMENTFORMAT_FLOAT4 = TSDL_GPUVertexElementFormat(12); + + { 8-bit Signed Integers } + SDL_GPU_VERTEXELEMENTFORMAT_BYTE2 = TSDL_GPUVertexElementFormat(13); + SDL_GPU_VERTEXELEMENTFORMAT_BYTE4 = TSDL_GPUVertexElementFormat(14); + + { 8-bit Unsigned Integers } + SDL_GPU_VERTEXELEMENTFORMAT_UBYTE2 = TSDL_GPUVertexElementFormat(15); + SDL_GPU_VERTEXELEMENTFORMAT_UBYTE4 = TSDL_GPUVertexElementFormat(16); + + { 8-bit Signed Normalized } + SDL_GPU_VERTEXELEMENTFORMAT_BYTE2_NORM = TSDL_GPUVertexElementFormat(17); + SDL_GPU_VERTEXELEMENTFORMAT_BYTE4_NORM = TSDL_GPUVertexElementFormat(18); + + { 8-bit Unsigned Normalized } + SDL_GPU_VERTEXELEMENTFORMAT_UBYTE2_NORM = TSDL_GPUVertexElementFormat(19); + SDL_GPU_VERTEXELEMENTFORMAT_UBYTE4_NORM = TSDL_GPUVertexElementFormat(20); + + { 16-bit Signed Integers } + SDL_GPU_VERTEXELEMENTFORMAT_SHORT2 = TSDL_GPUVertexElementFormat(21); + SDL_GPU_VERTEXELEMENTFORMAT_SHORT4 = TSDL_GPUVertexElementFormat(22); + + { 16-bit Unsigned Integers } + SDL_GPU_VERTEXELEMENTFORMAT_USHORT2 = TSDL_GPUVertexElementFormat(23); + SDL_GPU_VERTEXELEMENTFORMAT_USHORT4 = TSDL_GPUVertexElementFormat(24); + + { 16-bit Signed Normalized } + SDL_GPU_VERTEXELEMENTFORMAT_SHORT2_NORM = TSDL_GPUVertexElementFormat(25); + SDL_GPU_VERTEXELEMENTFORMAT_SHORT4_NORM = TSDL_GPUVertexElementFormat(26); + + { 16-bit Unsigned Normalized } + SDL_GPU_VERTEXELEMENTFORMAT_USHORT2_NORM = TSDL_GPUVertexElementFormat(27); + SDL_GPU_VERTEXELEMENTFORMAT_USHORT4_NORM = TSDL_GPUVertexElementFormat(28); + + { 16-bit Floats } + SDL_GPU_VERTEXELEMENTFORMAT_HALF2 = TSDL_GPUVertexElementFormat(29); + SDL_GPU_VERTEXELEMENTFORMAT_HALF4 = TSDL_GPUVertexElementFormat(30); + +{* + * Specifies the rate at which vertex attributes are pulled from buffers. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + } +type + PPSDL_GPUVertexInputRate = ^PSDL_GPUVertexInputRate; + PSDL_GPUVertexInputRate = ^TSDL_GPUVertexInputRate; + TSDL_GPUVertexInputRate = type Integer; +const + SDL_GPU_VERTEXINPUTRATE_VERTEX = TSDL_GPUVertexInputRate(0); {*< Attribute addressing is a function of the vertex index. } + SDL_GPU_VERTEXINPUTRATE_INSTANCE = TSDL_GPUVertexInputRate(1); {*< Attribute addressing is a function of the instance index. } + +{* + * Specifies the fill mode of the graphics pipeline. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + } +type + PPSDL_GPUFillMode = ^PSDL_GPUFillMode; + PSDL_GPUFillMode = ^TSDL_GPUFillMode; + TSDL_GPUFillMode = type Integer; +const + SDL_GPU_FILLMODE_FILL = TSDL_GPUFillMode(0); {*< Polygons will be rendered via rasterization. } + SDL_GPU_FILLMODE_LINE = TSDL_GPUFillMode(1); {*< Polygon edges will be drawn as line segments. } + +{* + * Specifies the facing direction in which triangle faces will be culled. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + } +type + PPSDL_GPUCullMode = ^PSDL_GPUCullMode; + PSDL_GPUCullMode = ^TSDL_GPUCullMode; + TSDL_GPUCullMode = type Integer; +const + SDL_GPU_CULLMODE_NONE = TSDL_GPUCullMode(0); {*< No triangles are culled. } + SDL_GPU_CULLMODE_FRONT = TSDL_GPUCullMode(1); {*< Front-facing triangles are culled. } + SDL_GPU_CULLMODE_BACK = TSDL_GPUCullMode(2); {*< Back-facing triangles are culled. } + +{* + * Specifies the vertex winding that will cause a triangle to be determined to + * be front-facing. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + } +type + PPSDL_GPUFrontFace = ^PSDL_GPUFrontFace; + PSDL_GPUFrontFace = ^TSDL_GPUFrontFace; + TSDL_GPUFrontFace = type Integer; +const + SDL_GPU_FRONTFACE_COUNTER_CLOCKWISE = TSDL_GPUFrontFace(0); {*< A triangle with counter-clockwise vertex winding will be considered front-facing. } + SDL_GPU_FRONTFACE_CLOCKWISE = TSDL_GPUFrontFace(1); {*< A triangle with clockwise vertex winding will be considered front-facing. } + +{* + * Specifies a comparison operator for depth, stencil and sampler operations. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + } +type + PPSDL_GPUCompareOp = ^PSDL_GPUCompareOp; + PSDL_GPUCompareOp = ^TSDL_GPUCompareOp; + TSDL_GPUCompareOp = type Integer; +const + SDL_GPU_COMPAREOP_INVALID = TSDL_GPUCompareOp(0); + SDL_GPU_COMPAREOP_NEVER = TSDL_GPUCompareOp(1); {*< The comparison always evaluates false. } + SDL_GPU_COMPAREOP_LESS = TSDL_GPUCompareOp(2); {*< The comparison evaluates reference < test. } + SDL_GPU_COMPAREOP_EQUAL = TSDL_GPUCompareOp(3); {*< The comparison evaluates reference == test. } + SDL_GPU_COMPAREOP_LESS_OR_EQUAL = TSDL_GPUCompareOp(4); {*< The comparison evaluates reference <= test. } + SDL_GPU_COMPAREOP_GREATER = TSDL_GPUCompareOp(5); {*< The comparison evaluates reference > test. } + SDL_GPU_COMPAREOP_NOT_EQUAL = TSDL_GPUCompareOp(6); {*< The comparison evaluates reference != test. } + SDL_GPU_COMPAREOP_GREATER_OR_EQUAL = TSDL_GPUCompareOp(7); {*< The comparison evalutes reference >= test. } + SDL_GPU_COMPAREOP_ALWAYS = TSDL_GPUCompareOp(8); {*< The comparison always evaluates true. } + +{* + * Specifies what happens to a stored stencil value if stencil tests fail or + * pass. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + } +type + PPSDL_GPUStencilOp = ^PSDL_GPUStencilOp; + PSDL_GPUStencilOp = ^TSDL_GPUStencilOp; + TSDL_GPUStencilOp = type Integer; +const + SDL_GPU_STENCILOP_INVALID = TSDL_GPUStencilOp(0); + SDL_GPU_STENCILOP_KEEP = TSDL_GPUStencilOp(1); {*< Keeps the current value. } + SDL_GPU_STENCILOP_ZERO = TSDL_GPUStencilOp(2); {*< Sets the value to 0. } + SDL_GPU_STENCILOP_REPLACE = TSDL_GPUStencilOp(3); {*< Sets the value to reference. } + SDL_GPU_STENCILOP_INCREMENT_AND_CLAMP = TSDL_GPUStencilOp(4); {*< Increments the current value and clamps to the maximum value. } + SDL_GPU_STENCILOP_DECREMENT_AND_CLAMP = TSDL_GPUStencilOp(5); {*< Decrements the current value and clamps to 0. } + SDL_GPU_STENCILOP_INVERT = TSDL_GPUStencilOp(6); {*< Bitwise-inverts the current value. } + SDL_GPU_STENCILOP_INCREMENT_AND_WRAP = TSDL_GPUStencilOp(7); {*< Increments the current value and wraps back to 0. } + SDL_GPU_STENCILOP_DECREMENT_AND_WRAP = TSDL_GPUStencilOp(8); {*< Decrements the current value and wraps to the maximum value. } + +{* + * Specifies the operator to be used when pixels in a render target are + * blended with existing pixels in the texture. + * + * The source color is the value written by the fragment shader. The + * destination color is the value currently existing in the texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + } +type + PPSDL_GPUBlendOp = ^PSDL_GPUBlendOp; + PSDL_GPUBlendOp = ^TSDL_GPUBlendOp; + TSDL_GPUBlendOp = type Integer; +const + SDL_GPU_BLENDOP_INVALID = TSDL_GPUBlendOp(0); + SDL_GPU_BLENDOP_ADD = TSDL_GPUBlendOp(1); {*< (source * source_factor) + (destination * destination_factor) } + SDL_GPU_BLENDOP_SUBTRACT = TSDL_GPUBlendOp(2); {*< (source * source_factor) - (destination * destination_factor) } + SDL_GPU_BLENDOP_REVERSE_SUBTRACT = TSDL_GPUBlendOp(3); {*< (destination * destination_factor) - (source * source_factor) } + SDL_GPU_BLENDOP_MIN = TSDL_GPUBlendOp(4); {*< min(source, destination) } + SDL_GPU_BLENDOP_MAX = TSDL_GPUBlendOp(5); {*< max(source, destination) } + +{* + * Specifies a blending factor to be used when pixels in a render target are + * blended with existing pixels in the texture. + * + * The source color is the value written by the fragment shader. The + * destination color is the value currently existing in the texture. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + } +type + PPSDL_GPUBlendFactor = ^PSDL_GPUBlendFactor; + PSDL_GPUBlendFactor = ^TSDL_GPUBlendFactor; + TSDL_GPUBlendFactor = type Integer; +const + SDL_GPU_BLENDFACTOR_INVALID = TSDL_GPUBlendFactor(0); + SDL_GPU_BLENDFACTOR_ZERO = TSDL_GPUBlendFactor(1); {*< 0 } + SDL_GPU_BLENDFACTOR_ONE = TSDL_GPUBlendFactor(2); {*< 1 } + SDL_GPU_BLENDFACTOR_SRC_COLOR = TSDL_GPUBlendFactor(3); {*< source color } + SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_COLOR = TSDL_GPUBlendFactor(4); {*< 1 - source color } + SDL_GPU_BLENDFACTOR_DST_COLOR = TSDL_GPUBlendFactor(5); {*< destination color } + SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_COLOR = TSDL_GPUBlendFactor(6); {*< 1 - destination color } + SDL_GPU_BLENDFACTOR_SRC_ALPHA = TSDL_GPUBlendFactor(7); {*< source alpha } + SDL_GPU_BLENDFACTOR_ONE_MINUS_SRC_ALPHA = TSDL_GPUBlendFactor(8); {*< 1 - source alpha } + SDL_GPU_BLENDFACTOR_DST_ALPHA = TSDL_GPUBlendFactor(9); {*< destination alpha } + SDL_GPU_BLENDFACTOR_ONE_MINUS_DST_ALPHA = TSDL_GPUBlendFactor(10); {*< 1 - destination alpha } + SDL_GPU_BLENDFACTOR_CONSTANT_COLOR = TSDL_GPUBlendFactor(11); {*< blend constant } + SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR = TSDL_GPUBlendFactor(12); {*< 1 - blend constant } + SDL_GPU_BLENDFACTOR_SRC_ALPHA_SATURATE = TSDL_GPUBlendFactor(13); {*< min(source alpha, 1 - destination alpha) } + +{* + * Specifies which color components are written in a graphics pipeline. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + } +type + PPSDL_GPUColorComponentFlags = ^PSDL_GPUColorComponentFlags; + PSDL_GPUColorComponentFlags = ^TSDL_GPUColorComponentFlags; + TSDL_GPUColorComponentFlags = type cuint8; +const + SDL_GPU_COLORCOMPONENT_R = 1 shl 0; {*< the red component } + SDL_GPU_COLORCOMPONENT_G = 1 shl 1; {*< the green component } + SDL_GPU_COLORCOMPONENT_B = 1 shl 2; {*< the blue component } + SDL_GPU_COLORCOMPONENT_A = 1 shl 3; {*< the alpha component } + +{* + * Specifies a filter operation used by a sampler. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + } +type + PPSDL_GPUFilter = ^PSDL_GPUFilter; + PSDL_GPUFilter = ^TSDL_GPUFilter; + TSDL_GPUFilter = type Integer; +const + SDL_GPU_FILTER_NEAREST = TSDL_GPUFilter(0); {*< Point filtering. } + SDL_GPU_FILTER_LINEAR = TSDL_GPUFilter(1); {*< Linear filtering. } + +{* + * Specifies a mipmap mode used by a sampler. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + } +type + PPSDL_GPUSamplerMipmapMode = ^PSDL_GPUSamplerMipmapMode; + PSDL_GPUSamplerMipmapMode = ^TSDL_GPUSamplerMipmapMode; + TSDL_GPUSamplerMipmapMode = type Integer; +const + SDL_GPU_SAMPLERMIPMAPMODE_NEAREST = TSDL_GPUSamplerMipmapMode(0); {*< Point filtering. } + SDL_GPU_SAMPLERMIPMAPMODE_LINEAR = TSDL_GPUSamplerMipmapMode(1); {*< Linear filtering. } + +{* + * Specifies behavior of texture sampling when the coordinates exceed the 0-1 + * range. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + } +type + PPSDL_GPUSamplerAddressMode = ^PSDL_GPUSamplerAddressMode; + PSDL_GPUSamplerAddressMode = ^TSDL_GPUSamplerAddressMode; + TSDL_GPUSamplerAddressMode = type Integer; +const + SDL_GPU_SAMPLERADDRESSMODE_REPEAT = TSDL_GPUSamplerAddressMode(0); {*< Specifies that the coordinates will wrap around. } + SDL_GPU_SAMPLERADDRESSMODE_MIRRORED_REPEAT = TSDL_GPUSamplerAddressMode(1); {*< Specifies that the coordinates will wrap around mirrored. } + SDL_GPU_SAMPLERADDRESSMODE_CLAMP_TO_EDGE = TSDL_GPUSamplerAddressMode(2); {*< Specifies that the coordinates will clamp to the 0-1 range. } + +{* + * Specifies the timing that will be used to present swapchain textures to the + * OS. + * + * VSYNC mode will always be supported. IMMEDIATE and MAILBOX modes may not be + * supported on certain systems. + * + * It is recommended to query SDL_WindowSupportsGPUPresentMode after claiming + * the window if you wish to change the present mode to IMMEDIATE or MAILBOX. + * + * - VSYNC: Waits for vblank before presenting. No tearing is possible. If + * there is a pending image to present, the new image is enqueued for + * presentation. Disallows tearing at the cost of visual latency. + * - IMMEDIATE: Immediately presents. Lowest latency option, but tearing may + * occur. + * - MAILBOX: Waits for vblank before presenting. No tearing is possible. If + * there is a pending image to present, the pending image is replaced by the + * new image. Similar to VSYNC, but with reduced visual latency. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_SetGPUSwapchainParameters + * \sa SDL_WindowSupportsGPUPresentMode + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + } +type + PPSDL_GPUPresentMode = ^PSDL_GPUPresentMode; + PSDL_GPUPresentMode = ^TSDL_GPUPresentMode; + TSDL_GPUPresentMode = type Integer; +const + SDL_GPU_PRESENTMODE_VSYNC = TSDL_GPUPresentMode(0); + SDL_GPU_PRESENTMODE_IMMEDIATE = TSDL_GPUPresentMode(1); + SDL_GPU_PRESENTMODE_MAILBOX = TSDL_GPUPresentMode(2); + +{* + * Specifies the texture format and colorspace of the swapchain textures. + * + * SDR will always be supported. Other compositions may not be supported on + * certain systems. + * + * It is recommended to query SDL_WindowSupportsGPUSwapchainComposition after + * claiming the window if you wish to change the swapchain composition from + * SDR. + * + * - SDR: B8G8R8A8 or R8G8B8A8 swapchain. Pixel values are in sRGB encoding. + * - SDR_LINEAR: B8G8R8A8_SRGB or R8G8B8A8_SRGB swapchain. Pixel values are + * stored in memory in sRGB encoding but accessed in shaders in "linear + * sRGB" encoding which is sRGB but with a linear transfer function. + * - HDR_EXTENDED_LINEAR: R16G16B16A16_FLOAT swapchain. Pixel values are in + * extended linear sRGB encoding and permits values outside of the [0, 1] + * range. + * - HDR10_ST2084: A2R10G10B10 or A2B10G10R10 swapchain. Pixel values are in + * BT.2020 ST2084 (PQ) encoding. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_SetGPUSwapchainParameters + * \sa SDL_WindowSupportsGPUSwapchainComposition + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + } +type + PPSDL_GPUSwapchainComposition = ^PSDL_GPUSwapchainComposition; + PSDL_GPUSwapchainComposition = ^TSDL_GPUSwapchainComposition; + TSDL_GPUSwapchainComposition = type Integer; +const + SDL_GPU_SWAPCHAINCOMPOSITION_SDR = TSDL_GPUSwapchainComposition(0); + SDL_GPU_SWAPCHAINCOMPOSITION_SDR_LINEAR = TSDL_GPUSwapchainComposition(1); + SDL_GPU_SWAPCHAINCOMPOSITION_HDR_EXTENDED_LINEAR = TSDL_GPUSwapchainComposition(2); + SDL_GPU_SWAPCHAINCOMPOSITION_HDR10_ST2084 = TSDL_GPUSwapchainComposition(3); + +{ Structures } + +{* + * A structure specifying a viewport. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_SetGPUViewport + } +type + PPSDL_GPUViewport = ^PSDL_GPUViewport; + PSDL_GPUViewport = ^TSDL_GPUViewport; + TSDL_GPUViewport = record + x: cfloat; {*< The left offset of the viewport. } + y: cfloat; {*< The top offset of the viewport. } + w: cfloat; {*< The width of the viewport. } + h: cfloat; {*< The height of the viewport. } + min_depth: cfloat; {*< The minimum depth of the viewport. } + max_depth: cfloat; {*< The maximum depth of the viewport. } + end; + +{* + * A structure specifying parameters related to transferring data to or from a + * texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + } +type + PPSDL_GPUTextureTransferInfo = ^PSDL_GPUTextureTransferInfo; + PSDL_GPUTextureTransferInfo = ^TSDL_GPUTextureTransferInfo; + TSDL_GPUTextureTransferInfo = record + transfer_buffer: PSDL_GPUTransferBuffer; {*< The transfer buffer used in the transfer operation. } + offset: cuint32; {*< The starting byte of the image data in the transfer buffer. } + pixels_per_row: cuint32; {*< The number of pixels from one row to the next. } + rows_per_layer: cuint32; {*< The number of rows from one layer/depth-slice to the next. } + end; + +{* + * A structure specifying a location in a transfer buffer. + * + * Used when transferring buffer data to or from a transfer buffer. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + } +type + PPSDL_GPUTransferBufferLocation = ^PSDL_GPUTransferBufferLocation; + PSDL_GPUTransferBufferLocation = ^TSDL_GPUTransferBufferLocation; + TSDL_GPUTransferBufferLocation = record + transfer_buffer: PSDL_GPUTransferBuffer; {*< The transfer buffer used in the transfer operation. } + offset: cuint32; {*< The starting byte of the buffer data in the transfer buffer. } + end; + +{* + * A structure specifying a location in a texture. + * + * Used when copying data from one texture to another. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CopyGPUTextureToTexture + } +type + PPSDL_GPUTextureLocation = ^PSDL_GPUTextureLocation; + PSDL_GPUTextureLocation = ^TSDL_GPUTextureLocation; + TSDL_GPUTextureLocation = record + texture: PSDL_GPUTexture; {*< The texture used in the copy operation. } + mip_level: cuint32; {*< The mip level index of the location. } + layer: cuint32; {*< The layer index of the location. } + x: cuint32; {*< The left offset of the location. } + y: cuint32; {*< The top offset of the location. } + z: cuint32; {*< The front offset of the location. } + end; + +{* + * A structure specifying a region of a texture. + * + * Used when transferring data to or from a texture. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + } +type + PPSDL_GPUTextureRegion = ^PSDL_GPUTextureRegion; + PSDL_GPUTextureRegion = ^TSDL_GPUTextureRegion; + TSDL_GPUTextureRegion = record + texture: PSDL_GPUTexture; {*< The texture used in the copy operation. } + mip_level: cuint32; {*< The mip level index to transfer. } + layer: cuint32; {*< The layer index to transfer. } + x: cuint32; {*< The left offset of the region. } + y: cuint32; {*< The top offset of the region. } + z: cuint32; {*< The front offset of the region. } + w: cuint32; {*< The width of the region. } + h: cuint32; {*< The height of the region. } + d: cuint32; {*< The depth of the region. } + end; + +{* + * A structure specifying a region of a texture used in the blit operation. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BlitGPUTexture + } +type + PPSDL_GPUBlitRegion = ^PSDL_GPUBlitRegion; + PSDL_GPUBlitRegion = ^TSDL_GPUBlitRegion; + TSDL_GPUBlitRegion = record + texture: PSDL_GPUTexture; {*< The texture. } + mip_level: cuint32; {*< The mip level index of the region. } + layer_or_depth_plane: cuint32; {*< 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. } + x: cuint32; {*< The left offset of the region. } + y: cuint32; {*< The top offset of the region. } + w: cuint32; {*< The width of the region. } + h: cuint32; {*< The height of the region. } + end; + +{* + * A structure specifying a location in a buffer. + * + * Used when copying data between buffers. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CopyGPUBufferToBuffer + } +type + PPSDL_GPUBufferLocation = ^PSDL_GPUBufferLocation; + PSDL_GPUBufferLocation = ^TSDL_GPUBufferLocation; + TSDL_GPUBufferLocation = record + buffer: PSDL_GPUBuffer; {*< The buffer. } + offset: cuint32; {*< The starting byte within the buffer. } + end; + +{* + * A structure specifying a region of a buffer. + * + * Used when transferring data to or from buffers. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + } +type + PPSDL_GPUBufferRegion = ^PSDL_GPUBufferRegion; + PSDL_GPUBufferRegion = ^TSDL_GPUBufferRegion; + TSDL_GPUBufferRegion = record + buffer: PSDL_GPUBuffer; {*< The buffer. } + offset: cuint32; {*< The starting byte within the buffer. } + size: cuint32; {*< The size in bytes of the region. } + end; + +{* + * A structure specifying the parameters of an indirect draw command. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DrawGPUPrimitivesIndirect + } +type + PPSDL_GPUIndirectDrawCommand = ^PSDL_GPUIndirectDrawCommand; + PSDL_GPUIndirectDrawCommand = ^TSDL_GPUIndirectDrawCommand; + TSDL_GPUIndirectDrawCommand = record + num_vertices: cuint32; {*< The number of vertices to draw. } + num_instances: cuint32; {*< The number of instances to draw. } + first_vertex: cuint32; {*< The index of the first vertex to draw. } + first_instance: cuint32; {*< The ID of the first instance to draw. } + end; + +{* + * A structure specifying the parameters of an indexed indirect draw command. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + } +type + PPSDL_GPUIndexedIndirectDrawCommand = ^PSDL_GPUIndexedIndirectDrawCommand; + PSDL_GPUIndexedIndirectDrawCommand = ^TSDL_GPUIndexedIndirectDrawCommand; + TSDL_GPUIndexedIndirectDrawCommand = record + num_indices: cuint32; {*< The number of indices to draw per instance. } + num_instances: cuint32; {*< The number of instances to draw. } + first_index: cuint32; {*< The base index within the index buffer. } + vertex_offset: cint32; {*< The value added to the vertex index before indexing into the vertex buffer. } + first_instance: cuint32; {*< The ID of the first instance to draw. } + end; + +{* + * A structure specifying the parameters of an indexed dispatch command. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DispatchGPUComputeIndirect + } +type + PPSDL_GPUIndirectDispatchCommand = ^PSDL_GPUIndirectDispatchCommand; + PSDL_GPUIndirectDispatchCommand = ^TSDL_GPUIndirectDispatchCommand; + TSDL_GPUIndirectDispatchCommand = record + groupcount_x: cuint32; {*< The number of local workgroups to dispatch in the X dimension. } + groupcount_y: cuint32; {*< The number of local workgroups to dispatch in the Y dimension. } + groupcount_z: cuint32; {*< The number of local workgroups to dispatch in the Z dimension. } + end; + +{ State structures } +{* + * A structure specifying the parameters of a sampler. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUSampler + } +type + PPSDL_GPUSamplerCreateInfo = ^PSDL_GPUSamplerCreateInfo; + PSDL_GPUSamplerCreateInfo = ^TSDL_GPUSamplerCreateInfo; + TSDL_GPUSamplerCreateInfo = record + min_filter: TSDL_GPUFilter; {*< The minification filter to apply to lookups. } + mag_filter: TSDL_GPUFilter; {*< The magnification filter to apply to lookups. } + mipmap_mode: TSDL_GPUSamplerMipmapMode; {*< The mipmap filter to apply to lookups. } + address_mode_u: TSDL_GPUSamplerAddressMode; {*< The addressing mode for U coordinates outside [0, 1). } + address_mode_v: TSDL_GPUSamplerAddressMode; {*< The addressing mode for V coordinates outside [0, 1). } + address_mode_w: TSDL_GPUSamplerAddressMode; {*< The addressing mode for W coordinates outside [0, 1). } + mip_lod_bias: cfloat; {*< The bias to be added to mipmap LOD calculation. } + max_anisotropy: cfloat; {*< The anisotropy value clamp used by the sampler. If enable_anisotropy is false, this is ignored. } + compare_op: TSDL_GPUCompareOp; {*< The comparison operator to apply to fetched data before filtering. } + min_lod: cfloat; {*< Clamps the minimum of the computed LOD value. } + max_lod: cfloat; {*< Clamps the maximum of the computed LOD value. } + enable_anisotropy: cbool; {*< true to enable anisotropic filtering. } + enable_compare: cbool; {*< true to enable comparison against a reference value during lookups. } + padding1: cuint8; + padding2: cuint8; + + props: TSDL_PropertiesID; {*< A properties ID for extensions. Should be 0 if no extensions are needed. } + end; + +{* + * A structure specifying the parameters of vertex buffers used in a graphics + * pipeline. + * + * When you call SDL_BindGPUVertexBuffers, you specify the binding slots of + * the vertex buffers. For example if you called SDL_BindGPUVertexBuffers with + * a first_slot of 2 and num_bindings of 3, the binding slots 2, 3, 4 would be + * used by the vertex buffers you pass in. + * + * Vertex attributes are linked to buffers via the buffer_slot field of + * SDL_GPUVertexAttribute. For example, if an attribute has a buffer_slot of + * 0, then that attribute belongs to the vertex buffer bound at slot 0. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUVertexAttribute + * \sa SDL_GPUVertexInputState + } +type + PPSDL_GPUVertexBufferDescription = ^PSDL_GPUVertexBufferDescription; + PSDL_GPUVertexBufferDescription = ^TSDL_GPUVertexBufferDescription; + TSDL_GPUVertexBufferDescription = record + slot: cuint32; {*< The binding slot of the vertex buffer. } + pitch: cuint32; {*< The byte pitch between consecutive elements of the vertex buffer. } + input_rate: TSDL_GPUVertexInputRate; {*< Whether attribute addressing is a function of the vertex index or instance index. } + instance_step_rate: cuint32; {*< 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 } + end; + +{* + * A structure specifying a vertex attribute. + * + * All vertex attribute locations provided to an SDL_GPUVertexInputState must + * be unique. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUVertexBufferDescription + * \sa SDL_GPUVertexInputState + } +type + PPSDL_GPUVertexAttribute = ^PSDL_GPUVertexAttribute; + PSDL_GPUVertexAttribute = ^TSDL_GPUVertexAttribute; + TSDL_GPUVertexAttribute = record + location: cuint32; {*< The shader input location index. } + buffer_slot: cuint32; {*< The binding slot of the associated vertex buffer. } + format: TSDL_GPUVertexElementFormat; {*< The size and type of the attribute data. } + offset: cuint32; {*< The byte offset of this attribute relative to the start of the vertex element. } + end; + +{* + * A structure specifying the parameters of a graphics pipeline vertex input + * state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + * \sa SDL_GPUVertexBufferDescription + * \sa SDL_GPUVertexAttribute + } +type + PPSDL_GPUVertexInputState = ^PSDL_GPUVertexInputState; + PSDL_GPUVertexInputState = ^TSDL_GPUVertexInputState; + TSDL_GPUVertexInputState = record + vertex_buffer_descriptions: PSDL_GPUVertexBufferDescription; {*< A Pointer to an array of vertex buffer descriptions. } + num_vertex_buffers: cuint32; {*< The number of vertex buffer descriptions in the above array. } + vertex_attributes: PSDL_GPUVertexAttribute; {*< A Pointer to an array of vertex attribute descriptions. } + num_vertex_attributes: cuint32; {*< The number of vertex attribute descriptions in the above array. } + end; + +{* + * A structure specifying the stencil operation state of a graphics pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUDepthStencilState + } +type + PPSDL_GPUStencilOpState = ^PSDL_GPUStencilOpState; + PSDL_GPUStencilOpState = ^TSDL_GPUStencilOpState; + TSDL_GPUStencilOpState = record + fail_op: TSDL_GPUStencilOp; {*< The action performed on samples that fail the stencil test. } + pass_op: TSDL_GPUStencilOp; {*< The action performed on samples that pass the depth and stencil tests. } + depth_fail_op: TSDL_GPUStencilOp; {*< The action performed on samples that pass the stencil test and fail the depth test. } + compare_op: TSDL_GPUCompareOp; {*< The comparison operator used in the stencil test. } + end; + +{* + * A structure specifying the blend state of a color target. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUColorTargetDescription + } +type + PPSDL_GPUColorTargetBlendState = ^PSDL_GPUColorTargetBlendState; + PSDL_GPUColorTargetBlendState = ^TSDL_GPUColorTargetBlendState; + TSDL_GPUColorTargetBlendState = record + src_color_blendfactor: TSDL_GPUBlendFactor; {*< The value to be multiplied by the source RGB value. } + dst_color_blendfactor: TSDL_GPUBlendFactor; {*< The value to be multiplied by the destination RGB value. } + color_blend_op: TSDL_GPUBlendOp; {*< The blend operation for the RGB components. } + src_alpha_blendfactor: TSDL_GPUBlendFactor; {*< The value to be multiplied by the source alpha. } + dst_alpha_blendfactor: TSDL_GPUBlendFactor; {*< The value to be multiplied by the destination alpha. } + alpha_blend_op: TSDL_GPUBlendOp; {*< The blend operation for the alpha component. } + color_write_mask: TSDL_GPUColorComponentFlags; {*< A bitmask specifying which of the RGBA components are enabled for writing. Writes to all channels if enable_color_write_mask is false. } + enable_blend: cbool; {*< Whether blending is enabled for the color target. } + enable_color_write_mask: cbool; {*< Whether the color write mask is enabled. } + padding1: cuint8; + padding2: cuint8; + end; + +{* + * A structure specifying code and metadata for creating a shader object. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + } +type + PPSDL_GPUShaderCreateInfo = ^PSDL_GPUShaderCreateInfo; + PSDL_GPUShaderCreateInfo = ^TSDL_GPUShaderCreateInfo; + TSDL_GPUShaderCreateInfo = record + code_size: csize_t; {*< The size in bytes of the code pointed to. } + code: pcuint8; {*< A Pointer to shader code. } + entrypoint: PAnsiChar; {*< A Pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. } + format: TSDL_GPUShaderFormat; {*< The format of the shader code. } + stage: TSDL_GPUShaderStage; {*< The stage the shader program corresponds to. } + num_samplers: cuint32; {*< The number of samplers defined in the shader. } + num_storage_textures: cuint32; {*< The number of storage textures defined in the shader. } + num_storage_buffers: cuint32; {*< The number of storage buffers defined in the shader. } + num_uniform_buffers: cuint32; {*< The number of uniform buffers defined in the shader. } + + props: TSDL_PropertiesID; {*< A properties ID for extensions. Should be 0 if no extensions are needed. } + end; + +{* + * A structure specifying the parameters of a texture. + * + * Usage flags can be bitwise OR'd together for combinations of usages. Note + * that certain usage combinations are invalid, for example SAMPLER and + * GRAPHICS_STORAGE. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + * \sa SDL_GPUTextureType + * \sa SDL_GPUTextureFormat + * \sa SDL_GPUTextureUsageFlags + * \sa SDL_GPUSampleCount + } +type + PPSDL_GPUTextureCreateInfo = ^PSDL_GPUTextureCreateInfo; + PSDL_GPUTextureCreateInfo = ^TSDL_GPUTextureCreateInfo; + TSDL_GPUTextureCreateInfo = record + type_: TSDL_GPUTextureType; {*< The base dimensionality of the texture. } + format: TSDL_GPUTextureFormat; {*< The pixel format of the texture. } + usage: TSDL_GPUTextureUsageFlags; {*< How the texture is intended to be used by the client. } + width: cuint32; {*< The width of the texture. } + height: cuint32; {*< The height of the texture. } + layer_count_or_depth: cuint32; {*< 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. } + num_levels: cuint32; {*< The number of mip levels in the texture. } + sample_count: TSDL_GPUSampleCount; {*< The number of samples per texel. Only applies if the texture is used as a render target. } + + props: TSDL_PropertiesID; {*< A properties ID for extensions. Should be 0 if no extensions are needed. } + end; + +{* + * A structure specifying the parameters of a buffer. + * + * Usage flags can be bitwise OR'd together for combinations of usages. Note + * that certain combinations are invalid, for example VERTEX and INDEX. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + * \sa SDL_GPUBufferUsageFlags + } +type + PPSDL_GPUBufferCreateInfo = ^PSDL_GPUBufferCreateInfo; + PSDL_GPUBufferCreateInfo = ^TSDL_GPUBufferCreateInfo; + TSDL_GPUBufferCreateInfo = record + usage: TSDL_GPUBufferUsageFlags; {*< How the buffer is intended to be used by the client. } + size: cuint32; {*< The size in bytes of the buffer. } + + props: TSDL_PropertiesID; {*< A properties ID for extensions. Should be 0 if no extensions are needed. } + end; + +{* + * A structure specifying the parameters of a transfer buffer. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTransferBuffer + } +type + PPSDL_GPUTransferBufferCreateInfo = ^PSDL_GPUTransferBufferCreateInfo; + PSDL_GPUTransferBufferCreateInfo = ^TSDL_GPUTransferBufferCreateInfo; + TSDL_GPUTransferBufferCreateInfo = record + usage: TSDL_GPUTransferBufferUsage; {*< How the transfer buffer is intended to be used by the client. } + size: cuint32; {*< The size in bytes of the transfer buffer. } + + props: TSDL_PropertiesID; {*< A properties ID for extensions. Should be 0 if no extensions are needed. } + end; + +{ 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.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + } +type + PPSDL_GPURasterizerState = ^PSDL_GPURasterizerState; + PSDL_GPURasterizerState = ^TSDL_GPURasterizerState; + TSDL_GPURasterizerState = record + fill_mode: TSDL_GPUFillMode; {*< Whether polygons will be filled in or drawn as lines. } + cull_mode: TSDL_GPUCullMode; {*< The facing direction in which triangles will be culled. } + front_face: TSDL_GPUFrontFace; {*< The vertex winding that will cause a triangle to be determined as front-facing. } + depth_bias_constant_factor: cfloat; {*< A scalar factor controlling the depth value added to each fragment. } + depth_bias_clamp: cfloat; {*< The maximum depth bias of a fragment. } + depth_bias_slope_factor: cfloat; {*< A scalar factor applied to a fragment's slope in depth calculations. } + enable_depth_bias: cbool; {*< true to bias fragment depth values. } + enable_depth_clip: cbool; {*< true to enable depth clip, false to enable depth clamp. } + padding1: cuint8; + padding2: cuint8; + end; + +{* + * A structure specifying the parameters of the graphics pipeline multisample + * state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + } +type + PPSDL_GPUMultisampleState = ^PSDL_GPUMultisampleState; + PSDL_GPUMultisampleState = ^TSDL_GPUMultisampleState; + TSDL_GPUMultisampleState = record + sample_count: TSDL_GPUSampleCount; {*< The number of samples to be used in rasterization. } + sample_mask: cuint32; {*< Determines which samples get updated in the render targets. Treated as 0xFFFFFFFF if enable_mask is false. } + enable_mask: cbool; {*< Enables sample masking. } + padding1: cuint8; + padding2: cuint8; + padding3: cuint8; + end; + +{* + * A structure specifying the parameters of the graphics pipeline depth + * stencil state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + } +type + PPSDL_GPUDepthStencilState = ^PSDL_GPUDepthStencilState; + PSDL_GPUDepthStencilState = ^TSDL_GPUDepthStencilState; + TSDL_GPUDepthStencilState = record + compare_op: TSDL_GPUCompareOp; {*< The comparison operator used for depth testing. } + back_stencil_state: TSDL_GPUStencilOpState; {*< The stencil op state for back-facing triangles. } + front_stencil_state: TSDL_GPUStencilOpState; {*< The stencil op state for front-facing triangles. } + compare_mask: cuint8; {*< Selects the bits of the stencil values participating in the stencil test. } + write_mask: cuint8; {*< Selects the bits of the stencil values updated by the stencil test. } + enable_depth_test: cbool; {*< true enables the depth test. } + enable_depth_write: cbool; {*< true enables depth writes. Depth writes are always disabled when enable_depth_test is false. } + enable_stencil_test: cbool; {*< true enables the stencil test. } + padding1: cuint8; + padding2: cuint8; + padding3: cuint8; + end; + +{* + * A structure specifying the parameters of color targets used in a graphics + * pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineTargetInfo + } +type + PPSDL_GPUColorTargetDescription = ^PSDL_GPUColorTargetDescription; + PSDL_GPUColorTargetDescription = ^TSDL_GPUColorTargetDescription; + TSDL_GPUColorTargetDescription = record + format: TSDL_GPUTextureFormat; {*< The pixel format of the texture to be used as a color target. } + blend_state: TSDL_GPUColorTargetBlendState; {*< The blend state to be used for the color target. } + end; + +{* + * A structure specifying the descriptions of render targets used in a + * graphics pipeline. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_GPUGraphicsPipelineCreateInfo + } +type + PPSDL_GPUGraphicsPipelineTargetInfo = ^PSDL_GPUGraphicsPipelineTargetInfo; + PSDL_GPUGraphicsPipelineTargetInfo = ^TSDL_GPUGraphicsPipelineTargetInfo; + TSDL_GPUGraphicsPipelineTargetInfo = record + color_target_descriptions: PSDL_GPUColorTargetDescription; {*< A Pointer to an array of color target descriptions. } + num_color_targets: cuint32; {*< The number of color target descriptions in the above array. } + depth_stencil_format: TSDL_GPUTextureFormat; {*< The pixel format of the depth-stencil target. Ignored if has_depth_stencil_target is false. } + has_depth_stencil_target: cbool; {*< true specifies that the pipeline uses a depth-stencil target. } + padding1: cuint8; + padding2: cuint8; + padding3: cuint8; + end; + +{* + * A structure specifying the parameters of a graphics pipeline state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_GPUVertexInputState + * \sa SDL_GPUPrimitiveType + * \sa SDL_GPURasterizerState + * \sa SDL_GPUMultisampleState + * \sa SDL_GPUDepthStencilState + * \sa SDL_GPUGraphicsPipelineTargetInfo + } +type + PPSDL_GPUGraphicsPipelineCreateInfo = ^PSDL_GPUGraphicsPipelineCreateInfo; + PSDL_GPUGraphicsPipelineCreateInfo = ^TSDL_GPUGraphicsPipelineCreateInfo; + TSDL_GPUGraphicsPipelineCreateInfo = record + vertex_shader: PSDL_GPUShader; {*< The vertex shader used by the graphics pipeline. } + fragment_shader: PSDL_GPUShader; {*< The fragment shader used by the graphics pipeline. } + vertex_input_state: TSDL_GPUVertexInputState; {*< The vertex layout of the graphics pipeline. } + primitive_type: TSDL_GPUPrimitiveType; {*< The primitive topology of the graphics pipeline. } + rasterizer_state: TSDL_GPURasterizerState; {*< The rasterizer state of the graphics pipeline. } + multisample_state: TSDL_GPUMultisampleState; {*< The multisample state of the graphics pipeline. } + depth_stencil_state: TSDL_GPUDepthStencilState; {*< The depth-stencil state of the graphics pipeline. } + target_info: TSDL_GPUGraphicsPipelineTargetInfo; {*< Formats and blend modes for the render targets of the graphics pipeline. } + + props: TSDL_PropertiesID; {*< A properties ID for extensions. Should be 0 if no extensions are needed. } + end; + +{* + * A structure specifying the parameters of a compute pipeline state. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUComputePipeline + } +type + PPSDL_GPUComputePipelineCreateInfo = ^PSDL_GPUComputePipelineCreateInfo; + PSDL_GPUComputePipelineCreateInfo = ^TSDL_GPUComputePipelineCreateInfo; + TSDL_GPUComputePipelineCreateInfo = record + code_size: csize_t; {*< The size in bytes of the compute shader code pointed to. } + code: pcuint8; {*< A Pointer to compute shader code. } + entrypoint: PAnsiChar; {*< A Pointer to a null-terminated UTF-8 string specifying the entry point function name for the shader. } + format: TSDL_GPUShaderFormat; {*< The format of the compute shader code. } + num_samplers: cuint32; {*< The number of samplers defined in the shader. } + num_readonly_storage_textures: cuint32; {*< The number of readonly storage textures defined in the shader. } + num_readonly_storage_buffers: cuint32; {*< The number of readonly storage buffers defined in the shader. } + num_readwrite_storage_textures: cuint32; {*< The number of read-write storage textures defined in the shader. } + num_readwrite_storage_buffers: cuint32; {*< The number of read-write storage buffers defined in the shader. } + num_uniform_buffers: cuint32; {*< The number of uniform buffers defined in the shader. } + threadcount_x: cuint32; {*< The number of threads in the X dimension. This should match the value in the shader. } + threadcount_y: cuint32; {*< The number of threads in the Y dimension. This should match the value in the shader. } + threadcount_z: cuint32; {*< The number of threads in the Z dimension. This should match the value in the shader. } + + props: TSDL_PropertiesID; {*< A properties ID for extensions. Should be 0 if no extensions are needed. } + end; + +{* + * A structure specifying the parameters of a color target used by a render + * pass. + * + * The load_op field determines what is done with the texture at the beginning + * of the render pass. + * + * - LOAD: Loads the data currently in the texture. Not recommended for + * multisample textures as it requires significant memory bandwidth. + * - CLEAR: Clears the texture to a single color. + * - DONT_CARE: The driver will do whatever it wants with the texture memory. + * This is a good option if you know that every single pixel will be touched + * in the render pass. + * + * The store_op field determines what is done with the color results of the + * render pass. + * + * - STORE: Stores the results of the render pass in the texture. Not + * recommended for multisample textures as it requires significant memory + * bandwidth. + * - DONT_CARE: The driver will do whatever it wants with the texture memory. + * This is often a good option for depth/stencil textures. + * - RESOLVE: Resolves a multisample texture into resolve_texture, which must + * have a sample count of 1. Then the driver may discard the multisample + * texture memory. This is the most performant method of resolving a + * multisample target. + * - RESOLVE_AND_STORE: Resolves a multisample texture into the + * resolve_texture, which must have a sample count of 1. Then the driver + * stores the multisample texture's contents. Not recommended as it requires + * significant memory bandwidth. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + } +type + PPSDL_GPUColorTargetInfo = ^PSDL_GPUColorTargetInfo; + PSDL_GPUColorTargetInfo = ^TSDL_GPUColorTargetInfo; + TSDL_GPUColorTargetInfo = record + texture: PSDL_GPUTexture; {*< The texture that will be used as a color target by a render pass. } + mip_level: cuint32; {*< The mip level to use as a color target. } + layer_or_depth_plane: cuint32; {*< 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. } + clear_color: TSDL_FColor; {*< The color to clear the color target to at the start of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. } + load_op: TSDL_GPULoadOp; {*< What is done with the contents of the color target at the beginning of the render pass. } + store_op: TSDL_GPUStoreOp; {*< What is done with the results of the render pass. } + resolve_texture: PSDL_GPUTexture; {*< The texture that will receive the results of a multisample resolve operation. Ignored if a RESOLVE* store_op is not used. } + resolve_mip_level: cuint32; {*< The mip level of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. } + resolve_layer: cuint32; {*< The layer index of the resolve texture to use for the resolve operation. Ignored if a RESOLVE* store_op is not used. } + cycle: cbool; {*< true cycles the texture if the texture is bound and load_op is not LOAD } + cycle_resolve_texture: cbool; {*< true cycles the resolve texture if the resolve texture is bound. Ignored if a RESOLVE* store_op is not used. } + padding1: cuint8; + padding2: cuint8; + end; + +{* + * A structure specifying the parameters of a depth-stencil target used by a + * render pass. + * + * The load_op field determines what is done with the depth contents of the + * texture at the beginning of the render pass. + * + * - LOAD: Loads the depth values currently in the texture. + * - CLEAR: Clears the texture to a single depth. + * - DONT_CARE: The driver will do whatever it wants with the memory. This is + * a good option if you know that every single pixel will be touched in the + * render pass. + * + * The store_op field determines what is done with the depth results of the + * render pass. + * + * - STORE: Stores the depth results in the texture. + * - DONT_CARE: The driver will do whatever it wants with the depth results. + * This is often a good option for depth/stencil textures that don't need to + * be reused again. + * + * The stencil_load_op field determines what is done with the stencil contents + * of the texture at the beginning of the render pass. + * + * - LOAD: Loads the stencil values currently in the texture. + * - CLEAR: Clears the stencil values to a single value. + * - DONT_CARE: The driver will do whatever it wants with the memory. This is + * a good option if you know that every single pixel will be touched in the + * render pass. + * + * The stencil_store_op field determines what is done with the stencil results + * of the render pass. + * + * - STORE: Stores the stencil results in the texture. + * - DONT_CARE: The driver will do whatever it wants with the stencil results. + * This is often a good option for depth/stencil textures that don't need to + * be reused again. + * + * Note that depth/stencil targets do not support multisample resolves. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPURenderPass + } +type + PPSDL_GPUDepthStencilTargetInfo = ^PSDL_GPUDepthStencilTargetInfo; + PSDL_GPUDepthStencilTargetInfo = ^TSDL_GPUDepthStencilTargetInfo; + TSDL_GPUDepthStencilTargetInfo = record + texture: PSDL_GPUTexture; {*< The texture that will be used as the depth stencil target by the render pass. } + clear_depth: cfloat; {*< The value to clear the depth component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. } + load_op: TSDL_GPULoadOp; {*< What is done with the depth contents at the beginning of the render pass. } + store_op: TSDL_GPUStoreOp; {*< What is done with the depth results of the render pass. } + stencil_load_op: TSDL_GPULoadOp; {*< What is done with the stencil contents at the beginning of the render pass. } + stencil_store_op: TSDL_GPUStoreOp; {*< What is done with the stencil results of the render pass. } + cycle: cbool; {*< true cycles the texture if the texture is bound and any load ops are not LOAD } + clear_stencil: cuint8; {*< The value to clear the stencil component to at the beginning of the render pass. Ignored if SDL_GPU_LOADOP_CLEAR is not used. } + padding1: cuint8; + padding2: cuint8; + end; + +{* + * A structure containing parameters for a blit command. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BlitGPUTexture + } +type + PPSDL_GPUBlitInfo = ^PSDL_GPUBlitInfo; + PSDL_GPUBlitInfo = ^TSDL_GPUBlitInfo; + TSDL_GPUBlitInfo = record + source: TSDL_GPUBlitRegion; {*< The source region for the blit. } + destination: TSDL_GPUBlitRegion; {*< The destination region for the blit. } + load_op: TSDL_GPULoadOp; {*< What is done with the contents of the destination before the blit. } + clear_color: TSDL_FColor; {*< The color to clear the destination region to before the blit. Ignored if load_op is not SDL_GPU_LOADOP_CLEAR. } + flip_mode: TSDL_FlipMode; {*< The flip mode for the source region. } + filter: TSDL_GPUFilter; {*< The filter mode used when blitting. } + cycle: cbool; {*< true cycles the destination texture if it is already bound. } + padding1: cuint8; + padding2: cuint8; + padding3: cuint8; + end; + +{ Binding structs } + +{* + * A structure specifying parameters in a buffer binding call. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + } +type + PPSDL_GPUBufferBinding = ^PSDL_GPUBufferBinding; + PSDL_GPUBufferBinding = ^TSDL_GPUBufferBinding; + TSDL_GPUBufferBinding = record + buffer: PSDL_GPUBuffer; {*< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_VERTEX for SDL_BindGPUVertexBuffers, or SDL_GPU_BUFFERUSAGE_INDEX for SDL_BindGPUIndexBuffer. } + offset: cuint32; {*< The starting byte of the data to bind in the buffer. } + end; + +{* + * A structure specifying parameters in a sampler binding call. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + } +type + PPSDL_GPUTextureSamplerBinding = ^PSDL_GPUTextureSamplerBinding; + PSDL_GPUTextureSamplerBinding = ^TSDL_GPUTextureSamplerBinding; + TSDL_GPUTextureSamplerBinding = record + texture: PSDL_GPUTexture; {*< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_SAMPLER. } + sampler: PSDL_GPUSampler; {*< The sampler to bind. } + end; + +{* + * A structure specifying parameters related to binding buffers in a compute + * pass. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + } +type + PPSDL_GPUStorageBufferReadWriteBinding = ^PSDL_GPUStorageBufferReadWriteBinding; + PSDL_GPUStorageBufferReadWriteBinding = ^TSDL_GPUStorageBufferReadWriteBinding; + TSDL_GPUStorageBufferReadWriteBinding = record + buffer: PSDL_GPUBuffer; {*< The buffer to bind. Must have been created with SDL_GPU_BUFFERUSAGE_COMPUTE_STORAGE_WRITE. } + cycle: cbool; {*< true cycles the buffer if it is already bound. } + padding1: cuint8; + padding2: cuint8; + padding3: cuint8; + end; + +{* + * A structure specifying parameters related to binding textures in a compute + * pass. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_BeginGPUComputePass + } +type + PPSDL_GPUStorageTextureReadWriteBinding = ^PSDL_GPUStorageTextureReadWriteBinding; + PSDL_GPUStorageTextureReadWriteBinding = ^TSDL_GPUStorageTextureReadWriteBinding; + TSDL_GPUStorageTextureReadWriteBinding = record + texture: PSDL_GPUTexture; {*< The texture to bind. Must have been created with SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_WRITE or SDL_GPU_TEXTUREUSAGE_COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE. } + mip_level: cuint32; {*< The mip level index to bind. } + layer: cuint32; {*< The layer index to bind. } + cycle: cbool; {*< true cycles the texture if it is already bound. } + padding1: cuint8; + padding2: cuint8; + padding3: cuint8; + end; + +{ 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 nil to let SDL pick the optimal + * driver. + * \returns true if supported, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUDevice + } +function SDL_GPUSupportsShaderFormats(format_flags: TSDL_GPUShaderFormat; name: PAnsiChar): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GPUSupportsShaderFormats' {$ENDIF} {$ENDIF}; + +{* + * Checks for GPU runtime support. + * + * \param props the properties to use. + * \returns true if supported, false otherwise. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUDeviceWithProperties + } +function SDL_GPUSupportsProperties(props: TSDL_PropertiesID): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GPUSupportsProperties' {$ENDIF} {$ENDIF}; + +{* + * 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 nil to let SDL pick the optimal + * driver. + * \returns a GPU context on success or nil on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGPUShaderFormats + * \sa SDL_GetGPUDeviceDriver + * \sa SDL_DestroyGPUDevice + * \sa SDL_GPUSupportsShaderFormats + } +function SDL_CreateGPUDevice(format_flags: TSDL_GPUShaderFormat; debug_mode: cbool; name: PAnsiChar): PSDL_GPUDevice; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateGPUDevice' {$ENDIF} {$ENDIF}; + +{* + * Creates a GPU context. + * + * These are the supported properties: + * + * - `SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN`: enable debug mode + * properties and validations, defaults to true. + * - `SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN`: enable to prefer + * energy efficiency over maximum GPU performance, defaults to false. + * - `SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING`: the name of the GPU driver to + * use, if a specific one is desired. + * + * These are the current shader format properties: + * + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN`: The app is able to + * provide shaders for an NDA platform. + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN`: The app is able to + * provide SPIR-V shaders if applicable. + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN`: The app is able to + * provide DXBC shaders if applicable + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN`: The app is able to + * provide DXIL shaders if applicable. + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN`: The app is able to + * provide MSL shaders if applicable. + * - `SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN`: The app is able to + * provide Metal shader libraries if applicable. + * + * With the D3D12 renderer: + * + * - `SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING`: the prefix to + * use for all vertex semantics, default is "TEXCOORD". + * + * \param props the properties to use. + * \returns a GPU context on success or nil on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGPUShaderFormats + * \sa SDL_GetGPUDeviceDriver + * \sa SDL_DestroyGPUDevice + * \sa SDL_GPUSupportsProperties + } +function SDL_CreateGPUDeviceWithProperties(props: TSDL_PropertiesID): PSDL_GPUDevice; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateGPUDeviceWithProperties' {$ENDIF} {$ENDIF}; + +const + SDL_PROP_GPU_DEVICE_CREATE_DEBUGMODE_BOOLEAN = 'SDL.gpu.device.create.debugmode'; + SDL_PROP_GPU_DEVICE_CREATE_PREFERLOWPOWER_BOOLEAN = 'SDL.gpu.device.create.preferlowpower'; + SDL_PROP_GPU_DEVICE_CREATE_NAME_STRING = 'SDL.gpu.device.create.name'; + SDL_PROP_GPU_DEVICE_CREATE_SHADERS_PRIVATE_BOOLEAN = 'SDL.gpu.device.create.shaders.private'; + SDL_PROP_GPU_DEVICE_CREATE_SHADERS_SPIRV_BOOLEAN = 'SDL.gpu.device.create.shaders.spirv'; + SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXBC_BOOLEAN = 'SDL.gpu.device.create.shaders.dxbc'; + SDL_PROP_GPU_DEVICE_CREATE_SHADERS_DXIL_BOOLEAN = 'SDL.gpu.device.create.shaders.dxil'; + SDL_PROP_GPU_DEVICE_CREATE_SHADERS_MSL_BOOLEAN = 'SDL.gpu.device.create.shaders.msl'; + SDL_PROP_GPU_DEVICE_CREATE_SHADERS_METALLIB_BOOLEAN = 'SDL.gpu.device.create.shaders.metallib'; + SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING = 'SDL.gpu.device.create.d3d12.semantic'; + +{* + * Destroys a GPU context previously returned by SDL_CreateGPUDevice. + * + * \param device a GPU Context to destroy. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUDevice + } +procedure SDL_DestroyGPUDevice(device: PSDL_GPUDevice); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DestroyGPUDevice' {$ENDIF} {$ENDIF}; + +{* + * Get the number of GPU drivers compiled into SDL. + * + * \returns the number of built in GPU drivers. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetGPUDriver + } +function SDL_GetNumGPUDrivers: cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetNumGPUDrivers' {$ENDIF} {$ENDIF}; + +{* + * Get the name of a built in GPU driver. + * + * The GPU drivers are presented in the order in which they are normally + * checked during initialization. + * + * The names of drivers are all simple, low-ASCII identifiers, like "vulkan", + * "metal" or "direct3d12". These never have Unicode characters, and are not + * meant to be proper names. + * + * \param index the index of a GPU driver. + * \returns the name of the GPU driver with the given **index**. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetNumGPUDrivers + } +function SDL_GetGPUDriver(index: cint): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGPUDriver' {$ENDIF} {$ENDIF}; + +{* + * 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 nil on error. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetGPUDeviceDriver(device: PSDL_GPUDevice): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGPUDeviceDriver' {$ENDIF} {$ENDIF}; + +{* + * Returns the supported shader formats for this GPU context. + * + * \param device a GPU context to query. + * \returns a bitflag indicating which shader formats the driver is able to + * consume. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetGPUShaderFormats(device: PSDL_GPUDevice): TSDL_GPUShaderFormat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGPUShaderFormats' {$ENDIF} {$ENDIF}; + +{ State Creation } + +{* + * Creates a pipeline object to be used in a compute workflow. + * + * Shader resource bindings must be authored to follow a particular order + * depending on the shader format. + * + * For SPIR-V shaders, use the following resource sets: + * + * - 0: Sampled textures, followed by read-only storage textures, followed by + * read-only storage buffers + * - 1: Read-write storage textures, followed by read-write storage buffers + * - 2: Uniform buffers + * + * For DXBC and DXIL shaders, use the following register order: + * + * - (t[n], space0): Sampled textures, followed by read-only storage textures, + * followed by read-only storage buffers + * - (u[n], space1): Read-write storage textures, followed by read-write + * storage buffers + * - (b[n], space2): Uniform buffers + * + * For MSL/metallib, use the following order: + * + * - [[buffer]]: Uniform buffers, followed by read-only storage buffers, + * followed by read-write storage buffers + * - [[texture]]: Sampled textures, followed by read-only storage textures, + * followed by read-write storage textures + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the compute pipeline to + * create. + * \returns a compute pipeline object on success, or nil on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BindGPUComputePipeline + * \sa SDL_ReleaseGPUComputePipeline + } +function SDL_CreateGPUComputePipeline(device: PSDL_GPUDevice; createinfo: PSDL_GPUComputePipelineCreateInfo): PSDL_GPUComputePipeline; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateGPUComputePipeline' {$ENDIF} {$ENDIF}; + +const + SDL_PROP_GPU_COMPUTEPIPELINE_CREATE_NAME_STRING = 'SDL.gpu.computepipeline.create.name'; + +{* + * Creates a pipeline object to be used in a graphics workflow. + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the graphics pipeline to + * create. + * \returns a graphics pipeline object on success, or nil on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUShader + * \sa SDL_BindGPUGraphicsPipeline + * \sa SDL_ReleaseGPUGraphicsPipeline + } +function SDL_CreateGPUGraphicsPipeline(device: PSDL_GPUDevice; createinfo: PSDL_GPUGraphicsPipelineCreateInfo): PSDL_GPUGraphicsPipeline; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateGPUGraphicsPipeline' {$ENDIF} {$ENDIF}; + +const + SDL_PROP_GPU_GRAPHICSPIPELINE_CREATE_NAME_STRING = 'SDL.gpu.graphicspipeline.create.name'; + +{* + * Creates a sampler object to be used when binding textures in a graphics + * workflow. + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING`: a name that can be displayed + * in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the sampler to create. + * \returns a sampler object on success, or nil on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_ReleaseGPUSampler + } +function SDL_CreateGPUSampler(device: PSDL_GPUDevice; createinfo: PSDL_GPUSamplerCreateInfo): PSDL_GPUSampler; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateGPUSampler' {$ENDIF} {$ENDIF}; + +const + SDL_PROP_GPU_SAMPLER_CREATE_NAME_STRING = 'SDL.gpu.sampler.create.name'; + +{* + * Creates a shader to be used when creating a graphics pipeline. + * + * Shader resource bindings must be authored to follow a particular order + * depending on the shader format. + * + * For SPIR-V shaders, use the following resource sets: + * + * For vertex shaders: + * + * - 0: Sampled textures, followed by storage textures, followed by storage + * buffers + * - 1: Uniform buffers + * + * For fragment shaders: + * + * - 2: Sampled textures, followed by storage textures, followed by storage + * buffers + * - 3: Uniform buffers + * + * For DXBC and DXIL shaders, use the following register order: + * + * For vertex shaders: + * + * - (t[n], space0): Sampled textures, followed by storage textures, followed + * by storage buffers + * - (s[n], space0): Samplers with indices corresponding to the sampled + * textures + * - (b[n], space1): Uniform buffers + * + * For pixel shaders: + * + * - (t[n], space2): Sampled textures, followed by storage textures, followed + * by storage buffers + * - (s[n], space2): Samplers with indices corresponding to the sampled + * textures + * - (b[n], space3): Uniform buffers + * + * For MSL/metallib, use the following order: + * + * - [[texture]]: Sampled textures, followed by storage textures + * - [[sampler]]: Samplers with indices corresponding to the sampled textures + * - [[buffer]]: Uniform buffers, followed by storage buffers. Vertex buffer 0 + * is bound at [[buffer(14)]], vertex buffer 1 at [[buffer(15)]], and so on. + * Rather than manually authoring vertex buffer indices, use the + * [[stage_in]] attribute which will automatically use the vertex input + * information from the SDL_GPUGraphicsPipeline. + * + * Shader semantics other than system-value semantics do not matter in D3D12 + * and for ease of use the SDL implementation assumes that non system-value + * semantics will all be TEXCOORD. If you are using HLSL as the shader source + * language, your vertex semantics should start at TEXCOORD0 and increment + * like so: TEXCOORD1, TEXCOORD2, etc. If you wish to change the semantic + * prefix to something other than TEXCOORD you can use + * SDL_PROP_GPU_DEVICE_CREATE_D3D12_SEMANTIC_NAME_STRING with + * SDL_CreateGPUDeviceWithProperties(). + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_SHADER_CREATE_NAME_STRING`: a name that can be displayed in + * debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the shader to create. + * \returns a shader object on success, or nil on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUGraphicsPipeline + * \sa SDL_ReleaseGPUShader + } +function SDL_CreateGPUShader(device: PSDL_GPUDevice; createinfo: PSDL_GPUShaderCreateInfo): PSDL_GPUShader; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateGPUShader' {$ENDIF} {$ENDIF}; + +const + SDL_PROP_GPU_SHADER_CREATE_NAME_STRING = 'SDL.gpu.shader.create.name'; + +{* + * Creates a texture object to be used in graphics or compute workflows. + * + * The contents of this texture are undefined until data is written to the + * texture. + * + * Note that certain combinations of usage flags are invalid. For example, a + * texture cannot have both the SAMPLER and GRAPHICS_STORAGE_READ flags. + * + * If you request a sample count higher than the hardware supports, the + * implementation will automatically fall back to the highest available sample + * count. + * + * There are optional properties that can be provided through + * SDL_GPUTextureCreateInfo's `props`. These are the supported properties: + * + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this red intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this green intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this blue intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT`: (Direct3D 12 only) if + * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture + * to a color with this alpha intensity. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT`: (Direct3D 12 only) + * if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear + * the texture to a depth of this value. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8`: (Direct3D 12 + * only) if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, + * clear the texture to a stencil of this value. Defaults to zero. + * - `SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING`: a name that can be displayed + * in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the texture to create. + * \returns a texture object on success, or nil on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_BindGPUVertexSamplers + * \sa SDL_BindGPUVertexStorageTextures + * \sa SDL_BindGPUFragmentSamplers + * \sa SDL_BindGPUFragmentStorageTextures + * \sa SDL_BindGPUComputeStorageTextures + * \sa SDL_BlitGPUTexture + * \sa SDL_ReleaseGPUTexture + * \sa SDL_GPUTextureSupportsFormat + } +function SDL_CreateGPUTexture(device: PSDL_GPUDevice; createinfo: PSDL_GPUTextureCreateInfo): PSDL_GPUTexture; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateGPUTexture' {$ENDIF} {$ENDIF}; + +const + SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_R_FLOAT = 'SDL.gpu.texture.create.d3d12.clear.r'; + SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_G_FLOAT = 'SDL.gpu.texture.create.d3d12.clear.g'; + SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_B_FLOAT = 'SDL.gpu.texture.create.d3d12.clear.b'; + SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_A_FLOAT = 'SDL.gpu.texture.create.d3d12.clear.a'; + SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_DEPTH_FLOAT = 'SDL.gpu.texture.create.d3d12.clear.depth'; + SDL_PROP_GPU_TEXTURE_CREATE_D3D12_CLEAR_STENCIL_UINT8 = 'SDL.gpu.texture.create.d3d12.clear.stencil'; + SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING = 'SDL.gpu.texture.create.name'; + +{* + * Creates a buffer object to be used in graphics or compute workflows. + * + * The contents of this buffer are undefined until data is written to the + * buffer. + * + * Note that certain combinations of usage flags are invalid. For example, a + * buffer cannot have both the VERTEX and INDEX flags. + * + * For better understanding of underlying concepts and memory management with + * SDL GPU API, you may refer + * [this blog post](https://moonside.games/posts/sdl-gpu-concepts-cycling/) + * . + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING`: a name that can be displayed in + * debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the buffer to create. + * \returns a buffer object on success, or nil on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_CopyGPUBufferToBuffer + * \sa SDL_BindGPUVertexBuffers + * \sa SDL_BindGPUIndexBuffer + * \sa SDL_BindGPUVertexStorageBuffers + * \sa SDL_BindGPUFragmentStorageBuffers + * \sa SDL_DrawGPUPrimitivesIndirect + * \sa SDL_DrawGPUIndexedPrimitivesIndirect + * \sa SDL_BindGPUComputeStorageBuffers + * \sa SDL_DispatchGPUComputeIndirect + * \sa SDL_ReleaseGPUBuffer + } +function SDL_CreateGPUBuffer(device: PSDL_GPUDevice; createinfo: PSDL_GPUBufferCreateInfo): PSDL_GPUBuffer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateGPUBuffer' {$ENDIF} {$ENDIF}; + +const + SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING = 'SDL.gpu.buffer.create.name'; + +{* + * Creates a transfer buffer to be used when uploading to or downloading from + * graphics resources. + * + * Download buffers can be particularly expensive to create, so it is good + * practice to reuse them if data will be downloaded regularly. + * + * There are optional properties that can be provided through `props`. These + * are the supported properties: + * + * - `SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING`: a name that can be + * displayed in debugging tools. + * + * \param device a GPU Context. + * \param createinfo a struct describing the state of the transfer buffer to + * create. + * \returns a transfer buffer on success, or nil on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUBuffer + * \sa SDL_DownloadFromGPUBuffer + * \sa SDL_UploadToGPUTexture + * \sa SDL_DownloadFromGPUTexture + * \sa SDL_ReleaseGPUTransferBuffer + } +function SDL_CreateGPUTransferBuffer(device: PSDL_GPUDevice; createinfo: PSDL_GPUTransferBufferCreateInfo): PSDL_GPUTransferBuffer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateGPUTransferBuffer' {$ENDIF} {$ENDIF}; + +const + SDL_PROP_GPU_TRANSFERBUFFER_CREATE_NAME_STRING = 'SDL.gpu.transferbuffer.create.name'; + +{ Debug Naming } + +{* + * Sets an arbitrary string constant to label a buffer. + * + * You should use SDL_PROP_GPU_BUFFER_CREATE_NAME_STRING with + * SDL_CreateGPUBuffer instead of this function to avoid thread safety issues. + * + * \param device a GPU Context. + * \param buffer a buffer to attach the name to. + * \param text a UTF-8 string constant to mark as the name of the buffer. + * + * \threadsafety This function is not thread safe, you must make sure the + * buffer is not simultaneously used by any other thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUBuffer + } +procedure SDL_SetGPUBufferName(device: PSDL_GPUDevice; buffer: PSDL_GPUBuffer; text: PAnsiChar); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetGPUBufferName' {$ENDIF} {$ENDIF}; + +{* + * Sets an arbitrary string constant to label a texture. + * + * You should use SDL_PROP_GPU_TEXTURE_CREATE_NAME_STRING with + * SDL_CreateGPUTexture instead of this function to avoid thread safety + * issues. + * + * \param device a GPU Context. + * \param texture a texture to attach the name to. + * \param text a UTF-8 string constant to mark as the name of the texture. + * + * \threadsafety This function is not thread safe, you must make sure the + * texture is not simultaneously used by any other thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateGPUTexture + } +procedure SDL_SetGPUTextureName(device: PSDL_GPUDevice; texture: PSDL_GPUTexture; text: PAnsiChar); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetGPUTextureName' {$ENDIF} {$ENDIF}; + +{* + * Inserts an arbitrary string label into the command buffer callstream. + * + * Useful for debugging. + * + * \param command_buffer a command buffer. + * \param text a UTF-8 string constant to insert as the label. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_InsertGPUDebugLabel(command_buffer: PSDL_GPUCommandBuffer; text: PAnsiChar); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_InsertGPUDebugLabel' {$ENDIF} {$ENDIF}; + +{* + * Begins a debug group with an arbitary name. + * + * Used for denoting groups of calls when viewing the command buffer + * callstream in a graphics debugging tool. + * + * Each call to SDL_PushGPUDebugGroup must have a corresponding call to + * SDL_PopGPUDebugGroup. + * + * On some backends (e.g. Metal), pushing a debug group during a + * render/blit/compute pass will create a group that is scoped to the native + * pass rather than the command buffer. For best results, if you push a debug + * group during a pass, always pop it in the same pass. + * + * \param command_buffer a command buffer. + * \param name a UTF-8 string constant that names the group. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PopGPUDebugGroup + } +procedure SDL_PushGPUDebugGroup(command_buffer: PSDL_GPUCommandBuffer; name: PAnsiChar); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_PushGPUDebugGroup' {$ENDIF} {$ENDIF}; + +{* + * Ends the most-recently pushed debug group. + * + * \param command_buffer a command buffer. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PushGPUDebugGroup + } +procedure SDL_PopGPUDebugGroup(command_buffer: PSDL_GPUCommandBuffer); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_PopGPUDebugGroup' {$ENDIF} {$ENDIF}; + +{ Disposal } + +{* + * Frees the given texture as soon as it is safe to do so. + * + * You must not reference the texture after calling this function. + * + * \param device a GPU context. + * \param texture a texture to be destroyed. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_ReleaseGPUTexture(device: PSDL_GPUDevice; texture: PSDL_GPUTexture); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReleaseGPUTexture' {$ENDIF} {$ENDIF}; + +{* + * Frees the given sampler as soon as it is safe to do so. + * + * You must not reference the sampler after calling this function. + * + * \param device a GPU context. + * \param sampler a sampler to be destroyed. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_ReleaseGPUSampler(device: PSDL_GPUDevice; sampler: PSDL_GPUSampler); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReleaseGPUSampler' {$ENDIF} {$ENDIF}; + +{* + * Frees the given buffer as soon as it is safe to do so. + * + * You must not reference the buffer after calling this function. + * + * \param device a GPU context. + * \param buffer a buffer to be destroyed. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_ReleaseGPUBuffer(device: PSDL_GPUDevice; buffer: PSDL_GPUBuffer); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReleaseGPUBuffer' {$ENDIF} {$ENDIF}; + +{* + * Frees the given transfer buffer as soon as it is safe to do so. + * + * You must not reference the transfer buffer after calling this function. + * + * \param device a GPU context. + * \param transfer_buffer a transfer buffer to be destroyed. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_ReleaseGPUTransferBuffer(device: PSDL_GPUDevice; transfer_buffer: PSDL_GPUTransferBuffer); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReleaseGPUTransferBuffer' {$ENDIF} {$ENDIF}; + +{* + * Frees the given compute pipeline as soon as it is safe to do so. + * + * You must not reference the compute pipeline after calling this function. + * + * \param device a GPU context. + * \param compute_pipeline a compute pipeline to be destroyed. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_ReleaseGPUComputePipeline(device: PSDL_GPUDevice; compute_pipeline: PSDL_GPUComputePipeline); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReleaseGPUComputePipeline' {$ENDIF} {$ENDIF}; + +{* + * Frees the given shader as soon as it is safe to do so. + * + * You must not reference the shader after calling this function. + * + * \param device a GPU context. + * \param shader a shader to be destroyed. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_ReleaseGPUShader(device: PSDL_GPUDevice; shader: PSDL_GPUShader); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReleaseGPUShader' {$ENDIF} {$ENDIF}; + +{* + * Frees the given graphics pipeline as soon as it is safe to do so. + * + * You must not reference the graphics pipeline after calling this function. + * + * \param device a GPU context. + * \param graphics_pipeline a graphics pipeline to be destroyed. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_ReleaseGPUGraphicsPipeline(device: PSDL_GPUDevice; graphics_pipeline: PSDL_GPUGraphicsPipeline); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReleaseGPUGraphicsPipeline' {$ENDIF} {$ENDIF}; + +{* + * Acquire a command buffer. + * + * This command buffer is managed by the implementation and should not be + * freed by the user. The command buffer may only be used on the thread it was + * acquired on. The command buffer should be submitted on the thread it was + * acquired on. + * + * It is valid to acquire multiple command buffers on the same thread at once. + * In fact a common design pattern is to acquire two command buffers per frame + * where one is dedicated to render and compute passes and the other is + * dedicated to copy passes and other preparatory work such as generating + * mipmaps. Interleaving commands between the two command buffers reduces the + * total amount of passes overall which improves rendering performance. + * + * \param device a GPU context. + * \returns a command buffer, or nil on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + } +function SDL_AcquireGPUCommandBuffer(device: PSDL_GPUDevice): PSDL_GPUCommandBuffer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AcquireGPUCommandBuffer' {$ENDIF} {$ENDIF}; + +{ Uniform Data } + +{* + * 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.2.0. + } +procedure SDL_PushGPUVertexUniformData(command_buffer: PSDL_GPUCommandBuffer; slot_index: cuint32; data: Pointer; length: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_PushGPUVertexUniformData' {$ENDIF} {$ENDIF}; + +{* + * 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.2.0. + } +procedure SDL_PushGPUFragmentUniformData(command_buffer: PSDL_GPUCommandBuffer; slot_index: cuint32; data: Pointer; length: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_PushGPUFragmentUniformData' {$ENDIF} {$ENDIF}; + +{* + * 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.2.0. + } +procedure SDL_PushGPUComputeUniformData(command_buffer: PSDL_GPUCommandBuffer; slot_index: cuint32; data: Pointer; length: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_PushGPUComputeUniformData' {$ENDIF} {$ENDIF}; + +{ 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 + * nil. + * \returns a render pass handle. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_EndGPURenderPass + } +function SDL_BeginGPURenderPass(command_buffer: PSDL_GPUCommandBuffer; color_target_infos: PSDL_GPUColorTargetInfo; num_color_targets: cuint32; depth_stencil_target_info: PSDL_GPUDepthStencilTargetInfo): PSDL_GPURenderPass; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BeginGPURenderPass' {$ENDIF} {$ENDIF}; + +{* + * Binds a graphics pipeline on a render pass to be used in rendering. + * + * A graphics pipeline must be bound before making any draw calls. + * + * \param render_pass a render pass handle. + * \param graphics_pipeline the graphics pipeline to bind. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_BindGPUGraphicsPipeline(render_pass: PSDL_GPURenderPass; graphics_pipeline: PSDL_GPUGraphicsPipeline); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BindGPUGraphicsPipeline' {$ENDIF} {$ENDIF}; + +{* + * Sets the current viewport state on a command buffer. + * + * \param render_pass a render pass handle. + * \param viewport the viewport to set. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_SetGPUViewport(render_pass: PSDL_GPURenderPass; viewport: PSDL_GPUViewport); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetGPUViewport' {$ENDIF} {$ENDIF}; + +{* + * Sets the current scissor state on a command buffer. + * + * \param render_pass a render pass handle. + * \param scissor the scissor area to set. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_SetGPUScissor(render_pass: PSDL_GPURenderPass; scissor: PSDL_Rect); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetGPUScissor' {$ENDIF} {$ENDIF}; + +{* + * Sets the current blend constants on a command buffer. + * + * \param render_pass a render pass handle. + * \param blend_constants the blend constant color. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GPU_BLENDFACTOR_CONSTANT_COLOR + * \sa SDL_GPU_BLENDFACTOR_ONE_MINUS_CONSTANT_COLOR + } +procedure SDL_SetGPUBlendConstants(render_pass: PSDL_GPURenderPass; blend_constants: TSDL_FColor); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetGPUBlendConstants' {$ENDIF} {$ENDIF}; + +{* + * Sets the current stencil reference value on a command buffer. + * + * \param render_pass a render pass handle. + * \param reference the stencil reference value to set. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_SetGPUStencilReference(render_pass: PSDL_GPURenderPass; reference: cuint8); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetGPUStencilReference' {$ENDIF} {$ENDIF}; + +{* + * Binds vertex buffers on a command buffer for use with subsequent draw + * calls. + * + * \param render_pass a render pass handle. + * \param first_slot the vertex buffer slot to begin binding from. + * \param bindings an array of SDL_GPUBufferBinding structs containing vertex + * buffers and offset values. + * \param num_bindings the number of bindings in the bindings array. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_BindGPUVertexBuffers(render_pass: PSDL_GPURenderPass; first_slot: cuint32; bindings: PSDL_GPUBufferBinding; num_bindings: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BindGPUVertexBuffers' {$ENDIF} {$ENDIF}; + +{* + * Binds an index buffer on a command buffer for use with subsequent draw + * calls. + * + * \param render_pass a render pass handle. + * \param binding a Pointer to a struct containing an index buffer and offset. + * \param index_element_size whether the index values in the buffer are 16- or + * 32-bit. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_BindGPUIndexBuffer(render_pass: PSDL_GPURenderPass; binding: PSDL_GPUBufferBinding; index_element_size: TSDL_GPUIndexElementSize); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BindGPUIndexBuffer' {$ENDIF} {$ENDIF}; + +{* + * 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.2.0. + } +procedure SDL_BindGPUVertexSamplers(render_pass: PSDL_GPURenderPass; first_slot: cuint32; texture_sampler_bindings: PSDL_GPUTextureSamplerBinding; num_bindings: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BindGPUVertexSamplers' {$ENDIF} {$ENDIF}; + +{* + * 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.2.0. + } +procedure SDL_BindGPUVertexStorageTextures(render_pass: PSDL_GPURenderPass; first_slot: cuint32; storage_textures: PPSDL_GPUTexture; num_bindings: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BindGPUVertexStorageTextures' {$ENDIF} {$ENDIF}; + +{* + * 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.2.0. + } +procedure SDL_BindGPUVertexStorageBuffers(render_pass: PSDL_GPURenderPass; first_slot: cuint32; storage_buffers: PPSDL_GPUBuffer; num_bindings: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BindGPUVertexStorageBuffers' {$ENDIF} {$ENDIF}; + +{* + * 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.2.0. + } +procedure SDL_BindGPUFragmentSamplers(render_pass: PSDL_GPURenderPass; first_slot: cuint32; texture_sampler_bindings: PSDL_GPUTextureSamplerBinding; num_bindings: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BindGPUFragmentSamplers' {$ENDIF} {$ENDIF}; + +{* + * 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.2.0. + } +procedure SDL_BindGPUFragmentStorageTextures(render_pass: PSDL_GPURenderPass; first_slot: cuint32; storage_textures: PPSDL_GPUTexture; num_bindings: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BindGPUFragmentStorageTextures' {$ENDIF} {$ENDIF}; + +{* + * 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.2.0. + } +procedure SDL_BindGPUFragmentStorageBuffers(render_pass: PSDL_GPURenderPass; first_slot: cuint32; storage_buffers: PPSDL_GPUBuffer; num_bindings: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BindGPUFragmentStorageBuffers' {$ENDIF} {$ENDIF}; + +{ Drawing } + +{* + * Draws data using bound graphics state with an index buffer and instancing + * enabled. + * + * You must not call this function before binding a graphics pipeline. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \param render_pass a render pass handle. + * \param num_indices the number of indices to draw per instance. + * \param num_instances the number of instances to draw. + * \param first_index the starting index within the index buffer. + * \param vertex_offset value added to vertex index before indexing into the + * vertex buffer. + * \param first_instance the ID of the first instance to draw. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_DrawGPUIndexedPrimitives(render_pass: PSDL_GPURenderPass; num_indices: cuint32; num_instances: cuint32; first_index: cuint32; vertex_offset: cint32; first_instance: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DrawGPUIndexedPrimitives' {$ENDIF} {$ENDIF}; + +{* + * Draws data using bound graphics state. + * + * You must not call this function before binding a graphics pipeline. + * + * Note that the `first_vertex` and `first_instance` parameters are NOT + * compatible with built-in vertex/instance ID variables in shaders (for + * example, SV_VertexID); GPU APIs and shader languages do not define these + * built-in variables consistently, so if your shader depends on them, the + * only way to keep behavior consistent and portable is to always pass 0 for + * the correlating parameter in the draw calls. + * + * \param render_pass a render pass handle. + * \param num_vertices the number of vertices to draw. + * \param num_instances the number of instances that will be drawn. + * \param first_vertex the index of the first vertex to draw. + * \param first_instance the ID of the first instance to draw. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_DrawGPUPrimitives(render_pass: PSDL_GPURenderPass; num_vertices: cuint32; num_instances: cuint32; first_vertex: cuint32; first_instance: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DrawGPUPrimitives' {$ENDIF} {$ENDIF}; + +{* + * Draws data using bound graphics state and with draw parameters set from a + * buffer. + * + * The buffer must consist of tightly-packed draw parameter sets that each + * match the layout of SDL_GPUIndirectDrawCommand. You must not call this + * function before binding a graphics pipeline. + * + * \param render_pass a render pass handle. + * \param buffer a buffer containing draw parameters. + * \param offset the offset to start reading from the draw buffer. + * \param draw_count the number of draw parameter sets that should be read + * from the draw buffer. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_DrawGPUPrimitivesIndirect(render_pass: PSDL_GPURenderPass; buffer: PSDL_GPUBuffer; offset: cuint32; draw_count: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DrawGPUPrimitivesIndirect' {$ENDIF} {$ENDIF}; + +{* + * Draws data using bound graphics state with an index buffer enabled and with + * draw parameters set from a buffer. + * + * The buffer must consist of tightly-packed draw parameter sets that each + * match the layout of SDL_GPUIndexedIndirectDrawCommand. You must not call + * this function before binding a graphics pipeline. + * + * \param render_pass a render pass handle. + * \param buffer a buffer containing draw parameters. + * \param offset the offset to start reading from the draw buffer. + * \param draw_count the number of draw parameter sets that should be read + * from the draw buffer. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_DrawGPUIndexedPrimitivesIndirect(render_pass: PSDL_GPURenderPass; buffer: PSDL_GPUBuffer; offset: cuint32; draw_count: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DrawGPUIndexedPrimitivesIndirect' {$ENDIF} {$ENDIF}; + +{* + * Ends the given render pass. + * + * All bound graphics state on the render pass command buffer is unset. The + * render pass handle is now invalid. + * + * \param render_pass a render pass handle. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_EndGPURenderPass(render_pass: PSDL_GPURenderPass); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_EndGPURenderPass' {$ENDIF} {$ENDIF}; + +{ Compute Pass } +{* + * Begins a compute pass on a command buffer. + * + * A compute pass is defined by a set of texture subresources and buffers that + * may be written to by compute pipelines. These textures and buffers must + * have been created with the COMPUTE_STORAGE_WRITE bit or the + * COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE bit. If you do not create a texture + * with COMPUTE_STORAGE_SIMULTANEOUS_READ_WRITE, you must not read from the + * texture in the compute pass. All operations related to compute pipelines + * must take place inside of a compute pass. You must not begin another + * compute pass, or a render pass or copy pass before ending the compute pass. + * + * A VERY IMPORTANT NOTE - Reads and writes in compute passes are NOT + * implicitly synchronized. This means you may cause data races by both + * reading and writing a resource region in a compute pass, or by writing + * multiple times to a resource region. If your compute work depends on + * reading the completed output from a previous dispatch, you MUST end the + * current compute pass and begin a new one before you can safely access the + * data. Otherwise you will receive unexpected results. Reading and writing a + * texture in the same compute pass is only supported by specific texture + * formats. Make sure you check the format support! + * + * \param command_buffer a command buffer. + * \param storage_texture_bindings an array of writeable storage texture + * binding structs. + * \param num_storage_texture_bindings the number of storage textures to bind + * from the array. + * \param storage_buffer_bindings an array of writeable storage buffer binding + * structs. + * \param num_storage_buffer_bindings the number of storage buffers to bind + * from the array. + * \returns a compute pass handle. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_EndGPUComputePass + } +function SDL_BeginGPUComputePass(command_buffer: PSDL_GPUCommandBuffer; storage_texture_bindings: PSDL_GPUStorageTextureReadWriteBinding; num_storage_texture_bindings: cuint32; storage_buffer_bindings: PSDL_GPUStorageBufferReadWriteBinding; num_storage_buffer_bindings: cuint32): PSDL_GPUComputePass; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BeginGPUComputePass' {$ENDIF} {$ENDIF}; + +{* + * Binds a compute pipeline on a command buffer for use in compute dispatch. + * + * \param compute_pass a compute pass handle. + * \param compute_pipeline a compute pipeline to bind. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_BindGPUComputePipeline(compute_pass: PSDL_GPUComputePass; compute_pipeline: PSDL_GPUComputePipeline); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BindGPUComputePipeline' {$ENDIF} {$ENDIF}; + +{* + * 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.2.0. + } +procedure SDL_BindGPUComputeSamplers(compute_pass: PSDL_GPUComputePass; first_slot: cuint32; texture_sampler_bindings: PSDL_GPUTextureSamplerBinding; num_bindings: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BindGPUComputeSamplers' {$ENDIF} {$ENDIF}; + +{* + * 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.2.0. + } +procedure SDL_BindGPUComputeStorageTextures(compute_pass: PSDL_GPUComputePass; first_slot: cuint32; storage_textures: PPSDL_GPUTexture; num_bindings: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BindGPUComputeStorageTextures' {$ENDIF} {$ENDIF}; + +{* + * 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.2.0. + } +(* const before declarator ignored *) +procedure SDL_BindGPUComputeStorageBuffers(compute_pass: PSDL_GPUComputePass; first_slot: cuint32; storage_buffers: PPSDL_GPUBuffer; num_bindings: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BindGPUComputeStorageBuffers' {$ENDIF} {$ENDIF}; + +{* + * Dispatches compute work. + * + * You must not call this function before binding a compute pipeline. + * + * A VERY IMPORTANT NOTE If you dispatch multiple times in a compute pass, and + * the dispatches write to the same resource region as each other, there is no + * guarantee of which order the writes will occur. If the write order matters, + * you MUST end the compute pass and begin another one. + * + * \param compute_pass a compute pass handle. + * \param groupcount_x number of local workgroups to dispatch in the X + * dimension. + * \param groupcount_y number of local workgroups to dispatch in the Y + * dimension. + * \param groupcount_z number of local workgroups to dispatch in the Z + * dimension. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_DispatchGPUCompute(compute_pass: PSDL_GPUComputePass; groupcount_x: cuint32; groupcount_y: cuint32; groupcount_z: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DispatchGPUCompute' {$ENDIF} {$ENDIF}; + +{* + * Dispatches compute work with parameters set from a buffer. + * + * The buffer layout should match the layout of + * SDL_GPUIndirectDispatchCommand. You must not call this function before + * binding a compute pipeline. + * + * A VERY IMPORTANT NOTE If you dispatch multiple times in a compute pass, and + * the dispatches write to the same resource region as each other, there is no + * guarantee of which order the writes will occur. If the write order matters, + * you MUST end the compute pass and begin another one. + * + * \param compute_pass a compute pass handle. + * \param buffer a buffer containing dispatch parameters. + * \param offset the offset to start reading from the dispatch buffer. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_DispatchGPUComputeIndirect(compute_pass: PSDL_GPUComputePass; buffer: PSDL_GPUBuffer; offset: cuint32); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DispatchGPUComputeIndirect' {$ENDIF} {$ENDIF}; + +{* + * Ends the current compute pass. + * + * All bound compute state on the command buffer is unset. The compute pass + * handle is now invalid. + * + * \param compute_pass a compute pass handle. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_EndGPUComputePass(compute_pass: PSDL_GPUComputePass); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_EndGPUComputePass' {$ENDIF} {$ENDIF}; + +{ 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 nil on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_MapGPUTransferBuffer(device: PSDL_GPUDevice; transfer_buffer: PSDL_GPUTransferBuffer; cycle: cbool): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_MapGPUTransferBuffer' {$ENDIF} {$ENDIF}; + +{* + * Unmaps a previously mapped transfer buffer. + * + * \param device a GPU context. + * \param transfer_buffer a previously mapped transfer buffer. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_UnmapGPUTransferBuffer(device: PSDL_GPUDevice; transfer_buffer: PSDL_GPUTransferBuffer); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UnmapGPUTransferBuffer' {$ENDIF} {$ENDIF}; + +{ Copy Pass } + +{* + * Begins a copy pass on a command buffer. + * + * All operations related to copying to or from buffers or textures take place + * inside a copy pass. You must not begin another copy pass, or a render pass + * or compute pass before ending the copy pass. + * + * \param command_buffer a command buffer. + * \returns a copy pass handle. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_BeginGPUCopyPass(command_buffer: PSDL_GPUCommandBuffer): PSDL_GPUCopyPass; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BeginGPUCopyPass' {$ENDIF} {$ENDIF}; + +{* + * Uploads data from a transfer buffer to a texture. + * + * The upload occurs on the GPU timeline. You may assume that the upload has + * finished in subsequent commands. + * + * You must align the data in the transfer buffer to a multiple of the texel + * size of the texture format. + * + * \param copy_pass a copy pass handle. + * \param source the source transfer buffer with image layout information. + * \param destination the destination texture region. + * \param cycle if true, cycles the texture if the texture is bound, otherwise + * overwrites the data. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_UploadToGPUTexture(copy_pass: PSDL_GPUCopyPass; source: PSDL_GPUTextureTransferInfo; destination: PSDL_GPUTextureRegion; cycle: cbool); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UploadToGPUTexture' {$ENDIF} {$ENDIF}; + +{* + * Uploads data from a transfer buffer to a buffer. + * + * The upload occurs on the GPU timeline. You may assume that the upload has + * finished in subsequent commands. + * + * \param copy_pass a copy pass handle. + * \param source the source transfer buffer with offset. + * \param destination the destination buffer with offset and size. + * \param cycle if true, cycles the buffer if it is already bound, otherwise + * overwrites the data. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_UploadToGPUBuffer(copy_pass: PSDL_GPUCopyPass; source: PSDL_GPUTransferBufferLocation; destination: PSDL_GPUBufferRegion; cycle: cbool); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UploadToGPUBuffer' {$ENDIF} {$ENDIF}; + +{* + * Performs a texture-to-texture copy. + * + * This copy occurs on the GPU timeline. You may assume the copy has finished + * in subsequent commands. + * + * \param copy_pass a copy pass handle. + * \param source a source texture region. + * \param destination a destination texture region. + * \param w the width of the region to copy. + * \param h the height of the region to copy. + * \param d the depth of the region to copy. + * \param cycle if true, cycles the destination texture if the destination + * texture is bound, otherwise overwrites the data. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_CopyGPUTextureToTexture(copy_pass: PSDL_GPUCopyPass; source: PSDL_GPUTextureLocation; destination: PSDL_GPUTextureLocation; w: cuint32; h: cuint32; d: cuint32; cycle: cbool); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CopyGPUTextureToTexture' {$ENDIF} {$ENDIF}; + +{* + * Performs a buffer-to-buffer copy. + * + * This copy occurs on the GPU timeline. You may assume the copy has finished + * in subsequent commands. + * + * \param copy_pass a copy pass handle. + * \param source the buffer and offset to copy from. + * \param destination the buffer and offset to copy to. + * \param size the length of the buffer to copy. + * \param cycle if true, cycles the destination buffer if it is already bound, + * otherwise overwrites the data. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_CopyGPUBufferToBuffer(copy_pass: PSDL_GPUCopyPass; source: PSDL_GPUBufferLocation; destination: PSDL_GPUBufferLocation; size: cuint32; cycle: cbool); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CopyGPUBufferToBuffer' {$ENDIF} {$ENDIF}; + +{* + * Copies data from a texture to a transfer buffer on the GPU timeline. + * + * This data is not guaranteed to be copied until the command buffer fence is + * signaled. + * + * \param copy_pass a copy pass handle. + * \param source the source texture region. + * \param destination the destination transfer buffer with image layout + * information. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_DownloadFromGPUTexture(copy_pass: PSDL_GPUCopyPass; source: PSDL_GPUTextureRegion; destination: PSDL_GPUTextureTransferInfo); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DownloadFromGPUTexture' {$ENDIF} {$ENDIF}; + +{* + * Copies data from a buffer to a transfer buffer on the GPU timeline. + * + * This data is not guaranteed to be copied until the command buffer fence is + * signaled. + * + * \param copy_pass a copy pass handle. + * \param source the source buffer with offset and size. + * \param destination the destination transfer buffer with offset. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_DownloadFromGPUBuffer(copy_pass: PSDL_GPUCopyPass; source: PSDL_GPUBufferRegion; destination: PSDL_GPUTransferBufferLocation); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DownloadFromGPUBuffer' {$ENDIF} {$ENDIF}; + +{* + * Ends the current copy pass. + * + * \param copy_pass a copy pass handle. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_EndGPUCopyPass(copy_pass: PSDL_GPUCopyPass); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_EndGPUCopyPass' {$ENDIF} {$ENDIF}; + +{* + * Generates mipmaps for the given texture. + * + * This function must not be called inside of any pass. + * + * \param command_buffer a command_buffer. + * \param texture a texture with more than 1 mip level. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_GenerateMipmapsForGPUTexture(command_buffer: PSDL_GPUCommandBuffer; texture: PSDL_GPUTexture); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GenerateMipmapsForGPUTexture' {$ENDIF} {$ENDIF}; + +{* + * Blits from a source texture region to a destination texture region. + * + * This function must not be called inside of any pass. + * + * \param command_buffer a command buffer. + * \param info the blit info struct containing the blit parameters. + * + * \since This function is available since SDL 3.2.0. + } + +procedure SDL_BlitGPUTexture(command_buffer: PSDL_GPUCommandBuffer; info: PSDL_GPUBlitInfo); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_BlitGPUTexture' {$ENDIF} {$ENDIF}; + +{ Submission/Presentation } + +{* + * Determines whether a swapchain composition is supported by the window. + * + * The window must be claimed before calling this function. + * + * \param device a GPU context. + * \param window an SDL_Window. + * \param swapchain_composition the swapchain composition to check. + * \returns true if supported, false if unsupported. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClaimWindowForGPUDevice + } +function SDL_WindowSupportsGPUSwapchainComposition(device: PSDL_GPUDevice; window: PSDL_Window; swapchain_composition: TSDL_GPUSwapchainComposition): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WindowSupportsGPUSwapchainComposition' {$ENDIF} {$ENDIF}; + +{* + * Determines whether a presentation mode is supported by the window. + * + * The window must be claimed before calling this function. + * + * \param device a GPU context. + * \param window an SDL_Window. + * \param present_mode the presentation mode to check. + * \returns true if supported, false if unsupported. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClaimWindowForGPUDevice + } +function SDL_WindowSupportsGPUPresentMode(device: PSDL_GPUDevice; window: PSDL_Window; present_mode: TSDL_GPUPresentMode): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WindowSupportsGPUPresentMode' {$ENDIF} {$ENDIF}; + +{* + * Claims a window, creating a swapchain structure for it. + * + * This must be called before SDL_AcquireGPUSwapchainTexture is called using + * the window. You should only call this function from the thread that created + * the window. + * + * The swapchain will be created with SDL_GPU_SWAPCHAINCOMPOSITION_SDR and + * SDL_GPU_PRESENTMODE_VSYNC. If you want to have different swapchain + * parameters, you must call SDL_SetGPUSwapchainParameters after claiming the + * window. + * + * \param device a GPU context. + * \param window an SDL_Window. + * \returns true on success, or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_ReleaseWindowFromGPUDevice + * \sa SDL_WindowSupportsGPUPresentMode + * \sa SDL_WindowSupportsGPUSwapchainComposition + } +function SDL_ClaimWindowForGPUDevice(device: PSDL_GPUDevice; window: PSDL_Window): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ClaimWindowForGPUDevice' {$ENDIF} {$ENDIF}; + +{* + * Unclaims a window, destroying its swapchain structure. + * + * \param device a GPU context. + * \param window an SDL_Window that has been claimed. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClaimWindowForGPUDevice + } +procedure SDL_ReleaseWindowFromGPUDevice(device: PSDL_GPUDevice; window: PSDL_Window); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReleaseWindowFromGPUDevice' {$ENDIF} {$ENDIF}; + +{* + * 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.2.0. + * + * \sa SDL_WindowSupportsGPUPresentMode + * \sa SDL_WindowSupportsGPUSwapchainComposition + } +function SDL_SetGPUSwapchainParameters(device: PSDL_GPUDevice; window: PSDL_Window; swapchain_composition: TSDL_GPUSwapchainComposition; present_mode: TSDL_GPUPresentMode): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetGPUSwapchainParameters' {$ENDIF} {$ENDIF}; + +{* + * Configures the maximum allowed number of frames in flight. + * + * The default value when the device is created is 2. This means that after + * you have submitted 2 frames for presentation, if the GPU has not finished + * working on the first frame, SDL_AcquireGPUSwapchainTexture() will fill the + * swapchain texture Pointer with nil, and + * SDL_WaitAndAcquireGPUSwapchainTexture() will block. + * + * Higher values increase throughput at the expense of visual latency. Lower + * values decrease visual latency at the expense of throughput. + * + * Note that calling this function will stall and flush the command queue to + * prevent synchronization issues. + * + * The minimum value of allowed frames in flight is 1, and the maximum is 3. + * + * \param device a GPU context. + * \param allowed_frames_in_flight the maximum number of frames that can be + * pending on the GPU. + * \returns true if successful, false on error; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_SetGPUAllowedFramesInFlight(device: PSDL_GPUDevice; allowed_frames_in_flight: cuint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetGPUAllowedFramesInFlight' {$ENDIF} {$ENDIF}; + +{* + * Obtains the texture format of the swapchain for the given window. + * + * Note that this format can change if the swapchain parameters change. + * + * \param device a GPU context. + * \param window an SDL_Window that has been claimed. + * \returns the texture format of the swapchain. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetGPUSwapchainTextureFormat(device: PSDL_GPUDevice; window: PSDL_Window): TSDL_GPUTextureFormat; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetGPUSwapchainTextureFormat' {$ENDIF} {$ENDIF}; + +{* + * Acquire a texture to use in presentation. + * + * When a swapchain texture is acquired on a command buffer, it will + * automatically be submitted for presentation when the command buffer is + * submitted. The swapchain texture should only be referenced by the command + * buffer used to acquire it. + * + * This function will fill the swapchain texture handle with nil if too many + * frames are in flight. This is not an error. + * + * If you use this function, it is possible to create a situation where many + * command buffers are allocated while the rendering context waits for the GPU + * to catch up, which will cause memory usage to grow. You should use + * SDL_WaitAndAcquireGPUSwapchainTexture() unless you know what you are doing + * with timing. + * + * The swapchain texture is managed by the implementation and must not be + * freed by the user. You MUST NOT call this function from any thread other + * than the one that created the window. + * + * \param command_buffer a command buffer. + * \param window a window that has been claimed. + * \param swapchain_texture a Pointer filled in with a swapchain texture + * handle. + * \param swapchain_texture_width a Pointer filled in with the swapchain + * texture width, may be nil. + * \param swapchain_texture_height a Pointer filled in with the swapchain + * texture height, may be nil. + * \returns true on success, false on error; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ClaimWindowForGPUDevice + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_CancelGPUCommandBuffer + * \sa SDL_GetWindowSizeInPixels + * \sa SDL_WaitForGPUSwapchain + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_SetGPUAllowedFramesInFlight + } +function SDL_AcquireGPUSwapchainTexture(command_buffer: PSDL_GPUCommandBuffer; window: PSDL_Window; swapchain_texture: PPSDL_GPUTexture; swapchain_texture_width: pcuint32; swapchain_texture_height: pcuint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AcquireGPUSwapchainTexture' {$ENDIF} {$ENDIF}; + +{* + * Blocks the thread until a swapchain texture is available to be acquired. + * + * \param device a GPU context. + * \param window a window that has been claimed. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUSwapchainTexture + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_SetGPUAllowedFramesInFlight + } +function SDL_WaitForGPUSwapchain(device: PSDL_GPUDevice; window: PSDL_Window): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WaitForGPUSwapchain' {$ENDIF} {$ENDIF}; + +{* + * Blocks the thread until a swapchain texture is available to be acquired, + * and then acquires it. + * + * When a swapchain texture is acquired on a command buffer, it will + * automatically be submitted for presentation when the command buffer is + * submitted. The swapchain texture should only be referenced by the command + * buffer used to acquire it. It is an error to call + * SDL_CancelGPUCommandBuffer() after a swapchain texture is acquired. + * + * This function can fill the swapchain texture handle with nil in certain + * cases, for example if the window is minimized. This is not an error. You + * should always make sure to check whether the Pointer is nil before + * actually using it. + * + * The swapchain texture is managed by the implementation and must not be + * freed by the user. You MUST NOT call this function from any thread other + * than the one that created the window. + * + * \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 nil. + * \param swapchain_texture_height a Pointer filled in with the swapchain + * texture height, may be nil. + * \returns true on success, false on error; call SDL_GetError() for more + * information. + * + * \threadsafety This function should only be called from the thread that + * created the window. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + } +function SDL_WaitAndAcquireGPUSwapchainTexture(command_buffer: PSDL_GPUCommandBuffer; window: PSDL_Window; swapchain_texture: PPSDL_GPUTexture; swapchain_texture_width: pcuint32; swapchain_texture_height: pcuint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WaitAndAcquireGPUSwapchainTexture' {$ENDIF} {$ENDIF}; + +{* + * Submits a command buffer so its commands can be processed on the GPU. + * + * It is invalid to use the command buffer after this is called. + * + * This must be called from the thread the command buffer was acquired on. + * + * All commands in the submission are guaranteed to begin executing before any + * command in a subsequent submission begins executing. + * + * \param command_buffer a command buffer. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_AcquireGPUSwapchainTexture + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + } +function SDL_SubmitGPUCommandBuffer(command_buffer: PSDL_GPUCommandBuffer): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SubmitGPUCommandBuffer' {$ENDIF} {$ENDIF}; + +{* + * 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 nil on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_AcquireGPUSwapchainTexture + * \sa SDL_SubmitGPUCommandBuffer + * \sa SDL_ReleaseGPUFence + } +function SDL_SubmitGPUCommandBufferAndAcquireFence(command_buffer: PSDL_GPUCommandBuffer): PSDL_GPUFence; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SubmitGPUCommandBufferAndAcquireFence' {$ENDIF} {$ENDIF}; + +{* + * Cancels a command buffer. + * + * None of the enqueued commands are executed. + * + * It is an error to call this function after a swapchain texture has been + * acquired. + * + * This must be called from the thread the command buffer was acquired on. + * + * You must not reference the command buffer after calling this function. + * + * \param command_buffer a command buffer. + * \returns true on success, false on error; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAndAcquireGPUSwapchainTexture + * \sa SDL_AcquireGPUCommandBuffer + * \sa SDL_AcquireGPUSwapchainTexture + } +function SDL_CancelGPUCommandBuffer(command_buffer: PSDL_GPUCommandBuffer): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CancelGPUCommandBuffer' {$ENDIF} {$ENDIF}; + +{* + * Blocks the thread until the GPU is completely idle. + * + * \param device a GPU context. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitForGPUFences + } +function SDL_WaitForGPUIdle(device: PSDL_GPUDevice): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WaitForGPUIdle' {$ENDIF} {$ENDIF}; + +{* + * Blocks the thread until the given fences are signaled. + * + * \param device a GPU context. + * \param wait_all if 0, wait for any fence to be signaled, if 1, wait for all + * fences to be signaled. + * \param fences an array of fences to wait on. + * \param num_fences the number of fences in the fences array. + * \returns true on success, false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + * \sa SDL_WaitForGPUIdle + } +function SDL_WaitForGPUFences(device: PSDL_GPUDevice; wait_all: cbool; fences: PPSDL_GPUFence; num_fences: cuint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WaitForGPUFences' {$ENDIF} {$ENDIF}; + +{* + * Checks the status of a fence. + * + * \param device a GPU context. + * \param fence a fence. + * \returns true if the fence is signaled, false if it is not. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + } +function SDL_QueryGPUFence(device: PSDL_GPUDevice; fence: PSDL_GPUFence): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_QueryGPUFence' {$ENDIF} {$ENDIF}; + +{* + * Releases a fence obtained from SDL_SubmitGPUCommandBufferAndAcquireFence. + * + * \param device a GPU context. + * \param fence a fence. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SubmitGPUCommandBufferAndAcquireFence + } +procedure SDL_ReleaseGPUFence(device: PSDL_GPUDevice; fence: PSDL_GPUFence); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReleaseGPUFence' {$ENDIF} {$ENDIF}; + +{ Format Info } + +{* + * Obtains the texel block size for a texture format. + * + * \param format the texture format you want to know the texel size of. + * \returns the texel block size of the texture format. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_UploadToGPUTexture + } +function SDL_GPUTextureFormatTexelBlockSize(format: TSDL_GPUTextureFormat): cuint32; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GPUTextureFormatTexelBlockSize' {$ENDIF} {$ENDIF}; + +{* + * Determines whether a texture format is supported for a given type and + * usage. + * + * \param device a GPU context. + * \param format the texture format to check. + * \param type the type of texture (2D, 3D, Cube). + * \param usage a bitmask of all usage scenarios to check. + * \returns whether the texture format is supported for this type and usage. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GPUTextureSupportsFormat(device: PSDL_GPUDevice; format: TSDL_GPUTextureFormat; type_: TSDL_GPUTextureType; usage: TSDL_GPUTextureUsageFlags): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GPUTextureSupportsFormat' {$ENDIF} {$ENDIF}; + +{* + * 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.2.0. + } +function SDL_GPUTextureSupportsSampleCount(device: PSDL_GPUDevice; format: TSDL_GPUTextureFormat; sample_count: TSDL_GPUSampleCount): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GPUTextureSupportsSampleCount' {$ENDIF} {$ENDIF}; + +{* + * Calculate the size in bytes of a texture format with dimensions. + * + * \param format a texture format. + * \param width width in pixels. + * \param height height in pixels. + * \param depth_or_layer_count depth for 3D textures or layer count otherwise. + * \returns the size of a texture with this format and dimensions. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_CalculateGPUTextureFormatSize(format: TSDL_GPUTextureFormat; width: cuint32; height: cuint32; depth_or_layer_count: cuint32): cuint32; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CalculateGPUTextureFormatSize' {$ENDIF} {$ENDIF}; + +{* + * Call this to suspend GPU operation on Xbox when you receive the + * SDL_EVENT_DID_ENTER_BACKGROUND event. + * + * Do NOT call any SDL_GPU functions after calling this function! This must + * also be called before calling SDL_GDKSuspendComplete. + * + * \param device a GPU context. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddEventWatch + } +procedure SDL_GDKSuspendGPU(device: PSDL_GPUDevice); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GDKSuspendGPU' {$ENDIF} {$ENDIF}; + +{* + * Call this to resume GPU operation on Xbox when you receive the + * SDL_EVENT_WILL_ENTER_FOREGROUND event. + * + * When resuming, this function MUST be called before calling any other + * SDL_GPU functions. + * + * \param device a GPU context. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddEventWatch + } +procedure SDL_GDKResumeGPU(device: PSDL_GPUDevice); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GDKResumeGPU' {$ENDIF} {$ENDIF}; + From f0d6f79518f104449b9664a535ca5d353941f78f Mon Sep 17 00:00:00 2001 From: Matthias Date: Wed, 5 Feb 2025 23:48:22 +0100 Subject: [PATCH 03/18] Add SDL_atomic.inc --- units/SDL3.pas | 12 + units/SDL_atomic.inc | 567 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 579 insertions(+) create mode 100644 units/SDL_atomic.inc diff --git a/units/SDL3.pas b/units/SDL3.pas index bdae772..9210645 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -110,6 +110,7 @@ interface {$I SDL_dialog.inc} // 3.2.0 {$I SDL_time.inc} // 3.2.0 {$I SDL_filesystem.inc} // 3.2.0 +{$I SDL_atomic.inc} // 3.2.0 implementation @@ -313,5 +314,16 @@ function SDL_WINDOWPOS_ISCENTERED(X: Integer): Boolean; Result := (X and $FFFF0000) = SDL_WINDOWPOS_CENTERED_MASK; end; +{ Macros from SDL_atomic.h } +function SDL_AtomicIncRef(a: PSDL_AtomicInt): cint; +begin + SDL_AtomicIncRef:=SDL_AddAtomicInt(a,1); +end; + +function SDL_AtomicDecRef(a: PSDL_AtomicInt): cbool; +begin + SDL_AtomicDecRef:=(SDL_AddAtomicInt(a,-1)=1); +end; + end. diff --git a/units/SDL_atomic.inc b/units/SDL_atomic.inc new file mode 100644 index 0000000..11d5c22 --- /dev/null +++ b/units/SDL_atomic.inc @@ -0,0 +1,567 @@ +{ + This file is part of: + + SDL3 for Pascal + (https://github.com/PascalGameDevelopment/SDL3-for-Pascal) + SPDX-License-Identifier: Zlib +} + +{* + * # CategoryAtomic + * + * Atomic operations. + * + * IMPORTANT: If you are not an expert in concurrent lockless programming, you + * should not be using any functions in this file. You should be protecting + * your data structures with full mutexes instead. + * + * ***Seriously, here be dragons!*** + * + * You can find out a little more about lockless programming and the subtle + * issues that can arise here: + * https://learn.microsoft.com/en-us/windows/win32/dxtecharts/lockless-programming + * + * There's also lots of good information here: + * + * - https://www.1024cores.net/home/lock-free-algorithms + * - https://preshing.com/ + * + * These operations may or may not actually be implemented using processor + * specific atomic operations. When possible they are implemented as true + * processor specific atomic operations. When that is not possible the are + * implemented using locks that *do* use the available atomic operations. + * + * All of the atomic operations that modify memory are full memory barriers. + } + +{* + * An atomic spinlock. + * + * The atomic locks are efficient spinlocks using CPU instructions, but are + * vulnerable to starvation and can spin forever if a thread holding a lock + * has been terminated. For this reason you should minimize the code executed + * inside an atomic lock and never do expensive things like API or system + * calls while holding them. + * + * They are also vulnerable to starvation if the thread holding the lock is + * lower priority than other threads and doesn't get scheduled. In general you + * should use mutexes instead, since they have better performance and + * contention behavior. + * + * The atomic locks are not safe to lock recursively. + * + * Porting Note: The spin lock functions and type are required and can not be + * emulated because they are used in the atomic emulation code. + } +type + PPSDL_SpinLock = ^PSDL_SpinLock; + PSDL_SpinLock = ^TSDL_SpinLock; + TSDL_SpinLock = cint; + +{* + * Try to lock a spin lock by setting it to a non-zero value. + * + * ***Please note that spinlocks are dangerous if you don't know what you're + * doing. Please be careful using any sort of spinlock!*** + * + * \param lock a Pointer to a lock variable. + * \returns true if the lock succeeded, false if the lock is already held. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockSpinlock + * \sa SDL_UnlockSpinlock + } +function SDL_TryLockSpinlock(lock: PSDL_SpinLock): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TryLockSpinlock' {$ENDIF} {$ENDIF}; + +{* + * Lock a spin lock by setting it to a non-zero value. + * + * ***Please note that spinlocks are dangerous if you don't know what you're + * doing. Please be careful using any sort of spinlock!*** + * + * \param lock a Pointer to a lock variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_TryLockSpinlock + * \sa SDL_UnlockSpinlock + } +procedure SDL_LockSpinlock(lock: PSDL_SpinLock); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LockSpinlock' {$ENDIF} {$ENDIF}; + +{* + * Unlock a spin lock by setting it to 0. + * + * Always returns immediately. + * + * ***Please note that spinlocks are dangerous if you don't know what you're + * doing. Please be careful using any sort of spinlock!*** + * + * \param lock a Pointer to a lock variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LockSpinlock + * \sa SDL_TryLockSpinlock + } +procedure SDL_UnlockSpinlock(lock: PSDL_SpinLock); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UnlockSpinlock' {$ENDIF} {$ENDIF}; + +{* + * Mark a compiler barrier. + * + * A compiler barrier prevents the compiler from reordering reads and writes + * to globally visible variables across the call. + * + * This macro only prevents the compiler from reordering reads and writes, it + * does not prevent the CPU from reordering reads and writes. However, all of + * the atomic operations that modify memory are full memory barriers. + * + * \threadsafety Obviously this macro is safe to use from any thread at any + * time, but if you find yourself needing this, you are probably + * dealing with some very sensitive code; be careful! + * + * \since This macro is available since SDL 3.2.0. + } + +{ #todo: SDL3-for-Pascal: This macro places a low-level hard-coded compiler barrier + instruction depending on the platform. Do we need it in Pascal? } + +{* + * Insert a memory release barrier (function version). + * + * Please refer to SDL_MemoryBarrierRelease for details. This is a function + * version, which might be useful if you need to use this functionality from a + * scripting language, etc. Also, some of the macro versions call this + * function behind the scenes, where more heavy lifting can happen inside of + * SDL. Generally, though, an app written in C/C++/etc should use the macro + * version, as it will be more efficient. + * + * \threadsafety Obviously this function is safe to use from any thread at any + * time, but if you find yourself needing this, you are probably + * dealing with some very sensitive code; be careful! + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierRelease + } +procedure SDL_MemoryBarrierReleaseFunction; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_MemoryBarrierReleaseFunction' {$ENDIF} {$ENDIF}; + +{* + * Insert a memory acquire barrier (function version). + * + * Please refer to SDL_MemoryBarrierRelease for details. This is a function + * version, which might be useful if you need to use this functionality from a + * scripting language, etc. Also, some of the macro versions call this + * function behind the scenes, where more heavy lifting can happen inside of + * SDL. Generally, though, an app written in C/C++/etc should use the macro + * version, as it will be more efficient. + * + * \threadsafety Obviously this function is safe to use from any thread at any + * time, but if you find yourself needing this, you are probably + * dealing with some very sensitive code; be careful! + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierAcquire + } +procedure SDL_MemoryBarrierAcquireFunction; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_MemoryBarrierAcquireFunction' {$ENDIF} {$ENDIF}; + +{* + * Insert a memory release barrier (macro version). + * + * Memory barriers are designed to prevent reads and writes from being + * reordered by the compiler and being seen out of order on multi-core CPUs. + * + * A typical pattern would be for thread A to write some data and a flag, and + * for thread B to read the flag and get the data. In this case you would + * insert a release barrier between writing the data and the flag, + * guaranteeing that the data write completes no later than the flag is + * written, and you would insert an acquire barrier between reading the flag + * and reading the data, to ensure that all the reads associated with the flag + * have completed. + * + * In this pattern you should always see a release barrier paired with an + * acquire barrier and you should gate the data reads/writes with a single + * flag variable. + * + * For more information on these semantics, take a look at the blog post: + * http://preshing.com/20120913/acquire-and-release-semantics + * + * This is the macro version of this functionality; if possible, SDL will use + * compiler intrinsics or inline assembly, but some platforms might need to + * call the function version of this, SDL_MemoryBarrierReleaseFunction to do + * the heavy lifting. Apps that can use the macro should favor it over the + * function. + * + * \threadsafety Obviously this macro is safe to use from any thread at any + * time, but if you find yourself needing this, you are probably + * dealing with some very sensitive code; be careful! + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierAcquire + * \sa SDL_MemoryBarrierReleaseFunction + } + +{ #todo: SDL3-for-Pascal: This macro places a low-level hard-coded memory barrier + instruction depending on the platform. Do we need it in Pascal? } + +{* + * Insert a memory acquire barrier (macro version). + * + * Please see SDL_MemoryBarrierRelease for the details on what memory barriers + * are and when to use them. + * + * This is the macro version of this functionality; if possible, SDL will use + * compiler intrinsics or inline assembly, but some platforms might need to + * call the function version of this, SDL_MemoryBarrierAcquireFunction, to do + * the heavy lifting. Apps that can use the macro should favor it over the + * function. + * + * \threadsafety Obviously this macro is safe to use from any thread at any + * time, but if you find yourself needing this, you are probably + * dealing with some very sensitive code; be careful! + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_MemoryBarrierRelease + * \sa SDL_MemoryBarrierAcquireFunction + } + +{ #todo: SDL3-for-Pascal: This macro places a low-level hard-coded memory barrier + instruction depending on the platform. Do we need it in Pascal? } + +{* + * A macro to insert a CPU-specific "pause" instruction into the program. + * + * This can be useful in busy-wait loops, as it serves as a hint to the CPU as + * to the program's intent; some CPUs can use this to do more efficient + * processing. On some platforms, this doesn't do anything, so using this + * macro might just be a harmless no-op. + * + * Note that if you are busy-waiting, there are often more-efficient + * approaches with other synchronization primitives: mutexes, semaphores, + * condition variables, etc. + * + * \threadsafety This macro is safe to use from any thread. + * + * \since This macro is available since SDL 3.2.0. + } + +{ SDL3-for-Pascal: This macro places a low-level hard-coded CPU pause + instruction depending on the platform. Do we need it in Pascal? } + +{* + * A type representing an atomic integer value. + * + * This can be used to manage a value that is synchronized across multiple + * CPUs without a race condition; when an app sets a value with + * SDL_SetAtomicInt all other threads, regardless of the CPU it is running on, + * will see that value when retrieved with SDL_GetAtomicInt, regardless of CPU + * caches, etc. + * + * This is also useful for atomic compare-and-swap operations: a thread can + * change the value as long as its current value matches expectations. When + * done in a loop, one can guarantee data consistency across threads without a + * lock (but the usual warnings apply: if you don't know what you're doing, or + * you don't do it carefully, you can confidently cause any number of + * disasters with this, so in most cases, you _should_ use a mutex instead of + * this!). + * + * This is a struct so people don't accidentally use numeric operations on it + * directly. You have to use SDL atomic functions. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CompareAndSwapAtomicInt + * \sa SDL_GetAtomicInt + * \sa SDL_SetAtomicInt + * \sa SDL_AddAtomicInt + } +type + PPSDL_AtomicInt = ^PSDL_AtomicInt; + PSDL_AtomicInt = ^TSDL_AtomicInt; + TSDL_AtomicInt = record + value: cint; + end; + +{* + * Set an atomic variable to a new value if it is currently an old value. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a Pointer to an SDL_AtomicInt variable to be modified. + * \param oldval the old value. + * \param newval the new value. + * \returns true if the atomic variable was set, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAtomicInt + * \sa SDL_SetAtomicInt + } +function SDL_CompareAndSwapAtomicInt(a: PSDL_AtomicInt; oldval: cint; newval: cint): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CompareAndSwapAtomicInt' {$ENDIF} {$ENDIF}; + +{* + * Set an atomic variable to a value. + * + * This function also acts as a full memory barrier. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a Pointer to an SDL_AtomicInt variable to be modified. + * \param v the desired value. + * \returns the previous value of the atomic variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAtomicInt + } +function SDL_SetAtomicInt(a: PSDL_AtomicInt; v: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetAtomicInt' {$ENDIF} {$ENDIF}; + +{* + * Get the value of an atomic variable. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a Pointer to an SDL_AtomicInt variable. + * \returns the current value of an atomic variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAtomicInt + } +function SDL_GetAtomicInt(a: PSDL_AtomicInt): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetAtomicInt' {$ENDIF} {$ENDIF}; + +{* + * Add to an atomic variable. + * + * This function also acts as a full memory barrier. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a Pointer to an SDL_AtomicInt variable to be modified. + * \param v the desired value to add. + * \returns the previous value of the atomic variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AtomicDecRef + * \sa SDL_AtomicIncRef + } +function SDL_AddAtomicInt(a: PSDL_AtomicInt; v: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AddAtomicInt' {$ENDIF} {$ENDIF}; + +{* + * Increment an atomic variable used as a reference count. + * + * ***Note: If you don't know what this macro is for, you shouldn't use it!*** + * + * \param a a Pointer to an SDL_AtomicInt to increment. + * \returns the previous value of the atomic variable. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AtomicDecRef + } +function SDL_AtomicIncRef(a: PSDL_AtomicInt): cint; + +{* + * Decrement an atomic variable used as a reference count. + * + * ***Note: If you don't know what this macro is for, you shouldn't use it!*** + * + * \param a a Pointer to an SDL_AtomicInt to increment. + * \returns true if the variable reached zero after decrementing, false + * otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_AtomicIncRef + } +function SDL_AtomicDecRef(a: PSDL_AtomicInt): cbool; + +{* + * A type representing an atomic unsigned 32-bit value. + * + * This can be used to manage a value that is synchronized across multiple + * CPUs without a race condition; when an app sets a value with + * SDL_SetAtomicU32 all other threads, regardless of the CPU it is running on, + * will see that value when retrieved with SDL_GetAtomicU32, regardless of CPU + * caches, etc. + * + * This is also useful for atomic compare-and-swap operations: a thread can + * change the value as long as its current value matches expectations. When + * done in a loop, one can guarantee data consistency across threads without a + * lock (but the usual warnings apply: if you don't know what you're doing, or + * you don't do it carefully, you can confidently cause any number of + * disasters with this, so in most cases, you _should_ use a mutex instead of + * this!). + * + * This is a struct so people don't accidentally use numeric operations on it + * directly. You have to use SDL atomic functions. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CompareAndSwapAtomicU32 + * \sa SDL_GetAtomicU32 + * \sa SDL_SetAtomicU32 + } +type + PPSDL_AtomicU32 = ^PSDL_AtomicU32; + PSDL_AtomicU32 = ^TSDL_AtomicU32; + TSDL_AtomicU32 = record + value: cuint32; + end; + +{* + * Set an atomic variable to a new value if it is currently an old value. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a Pointer to an SDL_AtomicU32 variable to be modified. + * \param oldval the old value. + * \param newval the new value. + * \returns true if the atomic variable was set, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAtomicU32 + * \sa SDL_SetAtomicU32 + } +function SDL_CompareAndSwapAtomicU32(a: PSDL_AtomicU32; oldval: cuint32; newval: cuint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CompareAndSwapAtomicU32' {$ENDIF} {$ENDIF}; + +{* + * Set an atomic variable to a value. + * + * This function also acts as a full memory barrier. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a Pointer to an SDL_AtomicU32 variable to be modified. + * \param v the desired value. + * \returns the previous value of the atomic variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetAtomicU32 + } +function SDL_SetAtomicU32(a: PSDL_AtomicU32; v: cuint32): cuint32; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetAtomicU32' {$ENDIF} {$ENDIF}; + +{* + * Get the value of an atomic variable. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a Pointer to an SDL_AtomicU32 variable. + * \returns the current value of an atomic variable. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetAtomicU32 + } +function SDL_GetAtomicU32(a: PSDL_AtomicU32): cuint32; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetAtomicU32' {$ENDIF} {$ENDIF}; + +{* + * Set a Pointer to a new value if it is currently an old value. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a Pointer to a Pointer. + * \param oldval the old Pointer value. + * \param newval the new Pointer value. + * \returns true if the Pointer was set, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CompareAndSwapAtomicInt + * \sa SDL_GetAtomicPointer + * \sa SDL_SetAtomicPointer + } +function SDL_CompareAndSwapAtomicPointer(a: PPointer; oldval: Pointer; newval: Pointer): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CompareAndSwapAtomicPointer' {$ENDIF} {$ENDIF}; + +{* + * Set a Pointer to a value atomically. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a Pointer to a Pointer. + * \param v the desired Pointer value. + * \returns the previous value of the Pointer. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CompareAndSwapAtomicPointer + * \sa SDL_GetAtomicPointer + } +function SDL_SetAtomicPointer(a: PPointer; v: Pointer): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetAtomicPointer' {$ENDIF} {$ENDIF}; + +{* + * Get the value of a Pointer atomically. + * + * ***Note: If you don't know what this function is for, you shouldn't use + * it!*** + * + * \param a a Pointer to a Pointer. + * \returns the current value of a Pointer. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CompareAndSwapAtomicPointer + * \sa SDL_SetAtomicPointer + } +function SDL_GetAtomicPointer(a: PPointer): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetAtomicPointer' {$ENDIF} {$ENDIF}; + From 7845f8b6b74e9529bab0ea6e2725d0e3811c2de8 Mon Sep 17 00:00:00 2001 From: Matthias Date: Thu, 6 Feb 2025 00:10:10 +0100 Subject: [PATCH 04/18] Add SDL_haptic.inc --- units/SDL3.pas | 1 + units/SDL_haptic.inc | 1453 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1454 insertions(+) create mode 100644 units/SDL_haptic.inc diff --git a/units/SDL3.pas b/units/SDL3.pas index 9210645..0a02a3c 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -99,6 +99,7 @@ interface {$I SDL_keyboard.inc} // 3.1.6-prev {$I SDL_joystick.inc} // 3.1.6-prev {$I SDL_gamepad.inc} // 3.2.0 +{$I SDL_haptic.inc} // 3.2.0 {$I SDL_pen.inc} // 3.1.6-prev {$I SDL_touch.inc} // 3.1.6-prev {$I SDL_camera.inc} // 3.1.6-prev diff --git a/units/SDL_haptic.inc b/units/SDL_haptic.inc new file mode 100644 index 0000000..2a4c6d6 --- /dev/null +++ b/units/SDL_haptic.inc @@ -0,0 +1,1453 @@ +{ + This file is part of: + + SDL3 for Pascal + (https://github.com/PascalGameDevelopment/SDL3-for-Pascal) + SPDX-License-Identifier: Zlib +} + +{* + * # CategoryHaptic + * + * The SDL haptic subsystem manages haptic (force feedback) devices. + * + * The basic usage is as follows: + * + * - Initialize the subsystem (SDL_INIT_HAPTIC). + * - Open a haptic device. + * - SDL_OpenHaptic() to open from index. + * - SDL_OpenHapticFromJoystick() to open from an existing joystick. + * - Create an effect (SDL_HapticEffect). + * - Upload the effect with SDL_CreateHapticEffect(). + * - Run the effect with SDL_RunHapticEffect(). + * - (optional) Free the effect with SDL_DestroyHapticEffect(). + * - Close the haptic device with SDL_CloseHaptic(). + * + * Simple rumble example: + * + * ```c + * SDL_Haptic *haptic = nil; + * + * // Open the device + * SDL_HapticID *haptics = SDL_GetHaptics(nil); + * if (haptics) + * haptic = SDL_OpenHaptic(haptics[0]); + * SDL_free(haptics); + * + * if (haptic == nil) + * return; + * + * // Initialize simple rumble + * if (!SDL_InitHapticRumble(haptic)) + * return; + * + * // Play effect at 50% strength for 2 seconds + * if (!SDL_PlayHapticRumble(haptic, 0.5, 2000)) + * return; + * SDL_Delay(2000); + * + * // Clean up + * SDL_CloseHaptic(haptic); + * ``` + * + * Complete example: + * + * ```c + * bool test_haptic(SDL_Joystick *joystick) + * + * SDL_Haptic *haptic; + * SDL_HapticEffect effect; + * int effect_id; + * + * // Open the device + * haptic = SDL_OpenHapticFromJoystick(joystick); + * if (haptic == nil) return false; // Most likely joystick isn't haptic + * + * // See if it can do sine waves + * if ((SDL_GetHapticFeatures(haptic) & SDL_HAPTIC_SINE)==0) + * SDL_CloseHaptic(haptic); // No sine effect + * return false; + * + * + * // Create the effect + * SDL_memset(&effect, 0, sizeof(SDL_HapticEffect)); // 0 is safe default + * effect.type = SDL_HAPTIC_SINE; + * effect.periodic.direction.type = SDL_HAPTIC_POLAR; // Polar coordinates + * effect.periodic.direction.dir[0] = 18000; // Force comes from south + * effect.periodic.period = 1000; // 1000 ms + * effect.periodic.magnitude = 20000; // 20000/32767 strength + * effect.periodic.length = 5000; // 5 seconds long + * effect.periodic.attack_length = 1000; // Takes 1 second to get max strength + * effect.periodic.fade_length = 1000; // Takes 1 second to fade away + * + * // Upload the effect + * effect_id = SDL_CreateHapticEffect(haptic, &effect); + * + * // Test the effect + * SDL_RunHapticEffect(haptic, effect_id, 1); + * SDL_Delay(5000); // Wait for the effect to finish + * + * // We destroy the effect, although closing the device also does this + * SDL_DestroyHapticEffect(haptic, effect_id); + * + * // Close the device + * SDL_CloseHaptic(haptic); + * + * return true; // Success + * + * ``` + * + * Note that the SDL haptic subsystem is not thread-safe. + } + +{ FIXME: + * + * At the moment the magnitude variables are mixed between signed/unsigned, and + * it is also not made clear that ALL of those variables expect a max of 0x7FFF. + * + * Some platforms may have higher precision than that (Linux FF, Windows XInput) + * so we should fix the inconsistency in favor of higher possible precision, + * adjusting for platforms that use different scales. + * -flibit + } + +{* + * The haptic structure used to identify an SDL haptic. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_OpenHaptic + * \sa SDL_OpenHapticFromJoystick + * \sa SDL_CloseHaptic + } +type + PPSDL_Haptic = ^PSDL_Haptic; + PSDL_Haptic = type Pointer; + +{* + * \name Haptic features + * + * Different haptic features a device can have. + } +{ @ } + +{* + * \name Haptic effects + } +{ @ } + +{* + * Constant effect supported. + * + * Constant haptic effect. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticCondition + } +const + SDL_HAPTIC_CONSTANT = 1 shl 0; +{* + * Sine wave effect supported. + * + * Periodic haptic effect that simulates sine waves. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticPeriodic + } + SDL_HAPTIC_SINE = 1 shl 1; + +{* + * Square wave effect supported. + * + * Periodic haptic effect that simulates square waves. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticPeriodic + } + SDL_HAPTIC_SQUARE = 1 shl 2; + +{* + * Triangle wave effect supported. + * + * Periodic haptic effect that simulates triangular waves. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticPeriodic + } + SDL_HAPTIC_TRIANGLE = 1 shl 3; + +{* + * Sawtoothup wave effect supported. + * + * Periodic haptic effect that simulates saw tooth up waves. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticPeriodic + } + SDL_HAPTIC_SAWTOOTHUP = 1 shl 4; + +{* + * Sawtoothdown wave effect supported. + * + * Periodic haptic effect that simulates saw tooth down waves. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticPeriodic + } + SDL_HAPTIC_SAWTOOTHDOWN = 1 shl 5; + +{* + * Ramp effect supported. + * + * Ramp haptic effect. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticRamp + } + SDL_HAPTIC_RAMP = 1 shl 6; + +{* + * Spring effect supported - uses axes position. + * + * Condition haptic effect that simulates a spring. Effect is based on the + * axes position. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticCondition + } + SDL_HAPTIC_SPRING = 1 shl 7; + +{* + * Damper effect supported - uses axes velocity. + * + * Condition haptic effect that simulates dampening. Effect is based on the + * axes velocity. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticCondition + } + SDL_HAPTIC_DAMPER = 1 shl 8; + +{* + * Inertia effect supported - uses axes acceleration. + * + * Condition haptic effect that simulates inertia. Effect is based on the axes + * acceleration. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticCondition + } + SDL_HAPTIC_INERTIA = 1 shl 9; + +{* + * Friction effect supported - uses axes movement. + * + * Condition haptic effect that simulates friction. Effect is based on the + * axes movement. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticCondition + } + SDL_HAPTIC_FRICTION = 1 shl 10; + +{* + * Left/Right effect supported. + * + * Haptic effect for direct control over high/low frequency motors. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticLeftRight + } + SDL_HAPTIC_LEFTRIGHT = 1 shl 11; + +{* + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + } + SDL_HAPTIC_RESERVED1 = 1 shl 12; + +{* + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + } + SDL_HAPTIC_RESERVED2 = 1 shl 13; + +{* + * Reserved for future use. + * + * \since This macro is available since SDL 3.2.0. + } + SDL_HAPTIC_RESERVED3 = 1 shl 14; + +{* + * Custom effect is supported. + * + * User defined custom haptic effect. + * + * \since This macro is available since SDL 3.2.0. + } + SDL_HAPTIC_CUSTOM = 1 shl 15; + +{ Haptic effects } + +{ These last few are features the device has, not effects } + +{* + * Device can set global gain. + * + * Device supports setting the global gain. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SetHapticGain + } + SDL_HAPTIC_GAIN = 1 shl 16; + +{* + * Device can set autocenter. + * + * Device supports setting autocenter. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_SetHapticAutocenter + } + SDL_HAPTIC_AUTOCENTER = 1 shl 17; + +{* + * Device can be queried for effect status. + * + * Device supports querying effect status. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_GetHapticEffectStatus + } + SDL_HAPTIC_STATUS = 1 shl 18; + +{* + * Device can be paused. + * + * Devices supports being paused. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_PauseHaptic + * \sa SDL_ResumeHaptic + } + SDL_HAPTIC_PAUSE = 1 shl 19; + +{* + * \name Direction encodings + } + +{* + * Uses polar coordinates for the direction. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticDirection + } + SDL_HAPTIC_POLAR = 0; + +{* + * Uses cartesian coordinates for the direction. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticDirection + } + SDL_HAPTIC_CARTESIAN = 1; + +{* + * Uses spherical coordinates for the direction. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticDirection + } + SDL_HAPTIC_SPHERICAL = 2; + +{* + * Use this value to play an effect on the steering wheel axis. + * + * This provides better compatibility across platforms and devices as SDL will + * guess the correct axis. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_HapticDirection + } + SDL_HAPTIC_STEERING_AXIS = 3; + +{ Direction encodings } + +{ Haptic features } + +{ + * Misc defines. + } + +{* + * Used to play a device an infinite number of times. + * + * \since This macro is available since SDL 3.2.0. + * + * \sa SDL_RunHapticEffect + } + SDL_HAPTIC_INFINITY = 4294967295; + +{* + * Structure that represents a haptic direction. + * + * This is the direction where the force comes from, instead of the direction + * in which the force is exerted. + * + * Directions can be specified by: + * + * - SDL_HAPTIC_POLAR: Specified by polar coordinates. + * - SDL_HAPTIC_CARTESIAN: Specified by cartesian coordinates. + * - SDL_HAPTIC_SPHERICAL: Specified by spherical coordinates. + * + * Cardinal directions of the haptic device are relative to the positioning of + * the device. North is considered to be away from the user. + * + * The following diagram represents the cardinal directions: + * + * ``` + * .--. + * |__| .-------. + * |=.| |.-----.| + * |--| || || + * | | |'-----'| + * |__|~')_____(' + * [ COMPUTER ] + * + * + * North (0,-1) + * ^ + * | + * | + * (-1,0) West <----[ HAPTIC ]----> East (1,0) + * | + * | + * v + * South (0,1) + * + * + * [ USER ] + * \|||/ + * (o o) + * ---ooO-(_)-Ooo--- + * ``` + * + * If type is SDL_HAPTIC_POLAR, direction is encoded by hundredths of a degree + * starting north and turning clockwise. SDL_HAPTIC_POLAR only uses the first + * `dir` parameter. The cardinal directions would be: + * + * - North: 0 (0 degrees) + * - East: 9000 (90 degrees) + * - South: 18000 (180 degrees) + * - West: 27000 (270 degrees) + * + * If type is SDL_HAPTIC_CARTESIAN, direction is encoded by three positions (X + * axis, Y axis and Z axis (with 3 axes)). SDL_HAPTIC_CARTESIAN uses the first + * three `dir` parameters. The cardinal directions would be: + * + * - North: 0,-1, 0 + * - East: 1, 0, 0 + * - South: 0, 1, 0 + * - West: -1, 0, 0 + * + * The Z axis represents the height of the effect if supported, otherwise it's + * unused. In cartesian encoding (1, 2) would be the same as (2, 4), you can + * use any multiple you want, only the direction matters. + * + * If type is SDL_HAPTIC_SPHERICAL, direction is encoded by two rotations. The + * first two `dir` parameters are used. The `dir` parameters are as follows + * (all values are in hundredths of degrees): + * + * - Degrees from (1, 0) rotated towards (0, 1). + * - Degrees towards (0, 0, 1) (device needs at least 3 axes). + * + * Example of force coming from the south with all encodings (force coming + * from the south means the user will have to pull the stick to counteract): + * + * ```c + * SDL_HapticDirection direction; + * + * // Cartesian directions + * direction.type = SDL_HAPTIC_CARTESIAN; // Using cartesian direction encoding. + * direction.dir[0] = 0; // X position + * direction.dir[1] = 1; // Y position + * // Assuming the device has 2 axes, we don't need to specify third parameter. + * + * // Polar directions + * direction.type = SDL_HAPTIC_POLAR; // We'll be using polar direction encoding. + * direction.dir[0] = 18000; // Polar only uses first parameter + * + * // Spherical coordinates + * direction.type = SDL_HAPTIC_SPHERICAL; // Spherical encoding + * direction.dir[0] = 9000; // Since we only have two axes we don't need more parameters. + * ``` + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_HAPTIC_POLAR + * \sa SDL_HAPTIC_CARTESIAN + * \sa SDL_HAPTIC_SPHERICAL + * \sa SDL_HAPTIC_STEERING_AXIS + * \sa SDL_HapticEffect + * \sa SDL_GetNumHapticAxes + } +type + PPSDL_HapticDirection = ^PSDL_HapticDirection; + PSDL_HapticDirection = ^TSDL_HapticDirection; + TSDL_HapticDirection = record + type_: cuint8; {*< The type of encoding. } + dir: array[0..2] of cint32; {*< The encoded direction. } + end; + +{* + * A structure containing a template for a Constant effect. + * + * This struct is exclusively for the SDL_HAPTIC_CONSTANT effect. + * + * A constant effect applies a constant force in the specified direction to + * the joystick. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_HAPTIC_CONSTANT + * \sa SDL_HapticEffect + } +type + PPSDL_HapticConstant = ^PSDL_HapticConstant; + PSDL_HapticConstant = ^TSDL_HapticConstant; + TSDL_HapticConstant = record + { Header } + type_: cuint16; {*< SDL_HAPTIC_CONSTANT } + direction: TSDL_HapticDirection; {*< Direction of the effect. } + + { Replay } + length: cuint32; {*< Duration of the effect. } + delay: cuint16; {*< Delay before starting the effect. } + + { Trigger } + button: cuint16; {*< Button that triggers the effect. } + interval: cuint16; {*< How soon it can be triggered again after button. } + + { Constant } + level: cint16; {*< Strength of the constant effect. } + + { Envelope } + attack_length: cuint16; {*< Duration of the attack. } + attack_level: cuint16; {*< Level at the start of the attack. } + fade_length: cuint16; {*< Duration of the fade. } + fade_level: cuint16; {*< Level at the end of the fade. } + end; + +{* + * A structure containing a template for a Periodic effect. + * + * The struct handles the following effects: + * + * - SDL_HAPTIC_SINE + * - SDL_HAPTIC_SQUARE + * - SDL_HAPTIC_TRIANGLE + * - SDL_HAPTIC_SAWTOOTHUP + * - SDL_HAPTIC_SAWTOOTHDOWN + * + * A periodic effect consists in a wave-shaped effect that repeats itself over + * time. The type determines the shape of the wave and the parameters + * determine the dimensions of the wave. + * + * Phase is given by hundredth of a degree meaning that giving the phase a + * value of 9000 will displace it 25% of its period. Here are sample values: + * + * - 0: No phase displacement. + * - 9000: Displaced 25% of its period. + * - 18000: Displaced 50% of its period. + * - 27000: Displaced 75% of its period. + * - 36000: Displaced 100% of its period, same as 0, but 0 is preferred. + * + * Examples: + * + * ``` + * SDL_HAPTIC_SINE + * __ __ __ __ + * / \ / \ / \ / + * / \__/ \__/ \__/ + * + * SDL_HAPTIC_SQUARE + * __ __ __ __ __ + * | | | | | | | | | | + * | |__| |__| |__| |__| | + * + * SDL_HAPTIC_TRIANGLE + * /\ /\ /\ /\ /\ + * / \ / \ / \ / \ / + * / \/ \/ \/ \/ + * + * SDL_HAPTIC_SAWTOOTHUP + * /| /| /| /| /| /| /| + * / | / | / | / | / | / | / | + * / |/ |/ |/ |/ |/ |/ | + * + * SDL_HAPTIC_SAWTOOTHDOWN + * \ |\ |\ |\ |\ |\ |\ | + * \ | \ | \ | \ | \ | \ | \ | + * \| \| \| \| \| \| \| + * ``` + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_HAPTIC_SINE + * \sa SDL_HAPTIC_SQUARE + * \sa SDL_HAPTIC_TRIANGLE + * \sa SDL_HAPTIC_SAWTOOTHUP + * \sa SDL_HAPTIC_SAWTOOTHDOWN + * \sa SDL_HapticEffect + } +type + PPSDL_HapticPeriodic = ^PSDL_HapticPeriodic; + PSDL_HapticPeriodic = ^TSDL_HapticPeriodic; + TSDL_HapticPeriodic = record + { Header } + type_: cuint16; {*< SDL_HAPTIC_SINE, SDL_HAPTIC_SQUARE + SDL_HAPTIC_TRIANGLE, SDL_HAPTIC_SAWTOOTHUP or + SDL_HAPTIC_SAWTOOTHDOWN } + direction: TSDL_HapticDirection; {*< Direction of the effect. } + + { Replay } + length: cuint32; {*< Duration of the effect. } + delay: cuint16; {*< Delay before starting the effect. } + + { Trigger } + button: cuint16; {*< Button that triggers the effect. } + interval: cuint16; {*< How soon it can be triggered again after button. } + + { Periodic } + period: cuint16; {*< Period of the wave. } + magnitude: cint16; {*< Peak value; if negative, equivalent to 180 degrees extra phase shift. } + offset: cint16; {*< Mean value of the wave. } + phase: cuint16; {*< Positive phase shift given by hundredth of a degree. } + + { Envelope } + attack_length: cuint16; {*< Duration of the attack. } + attack_level: cuint16; {*< Level at the start of the attack. } + fade_length: cuint16; {*< Duration of the fade. } + fade_level: cuint16; {*< Level at the end of the fade. } + end; + +{* + * A structure containing a template for a Condition effect. + * + * The struct handles the following effects: + * + * - SDL_HAPTIC_SPRING: Effect based on axes position. + * - SDL_HAPTIC_DAMPER: Effect based on axes velocity. + * - SDL_HAPTIC_INERTIA: Effect based on axes acceleration. + * - SDL_HAPTIC_FRICTION: Effect based on axes movement. + * + * Direction is handled by condition internals instead of a direction member. + * The condition effect specific members have three parameters. The first + * refers to the X axis, the second refers to the Y axis and the third refers + * to the Z axis. The right terms refer to the positive side of the axis and + * the left terms refer to the negative side of the axis. Please refer to the + * SDL_HapticDirection diagram for which side is positive and which is + * negative. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_HapticDirection + * \sa SDL_HAPTIC_SPRING + * \sa SDL_HAPTIC_DAMPER + * \sa SDL_HAPTIC_INERTIA + * \sa SDL_HAPTIC_FRICTION + * \sa SDL_HapticEffect + } +type + PPSDL_HapticCondition = ^PSDL_HapticCondition; + PSDL_HapticCondition = ^TSDL_HapticCondition; + TSDL_HapticCondition = record + { Header } + type_: cuint16; {*< SDL_HAPTIC_SPRING, SDL_HAPTIC_DAMPER, + SDL_HAPTIC_INERTIA or SDL_HAPTIC_FRICTION } + direction: TSDL_HapticDirection; {*< Direction of the effect. } + + { Replay } + length: cuint32; {*< Duration of the effect. } + delay: cuint16; {*< Delay before starting the effect. } + + { Trigger } + button: cuint16; {*< Button that triggers the effect. } + interval: cuint16; {*< How soon it can be triggered again after button. } + + { Condition } + right_sat: array[0..2] of cuint16; {*< Level when joystick is to the positive side; max 0xFFFF. } + left_sat: array[0..2] of cuint16; {*< Level when joystick is to the negative side; max 0xFFFF. } + right_coeff: array[0..2] of cint16; {*< How fast to increase the force towards the positive side. } + left_coeff: array[0..2] of cint16; {*< How fast to increase the force towards the negative side. } + deadband: array[0..2] of cuint16; {*< Size of the dead zone; max 0xFFFF: whole axis-range when 0-centered. } + center: array[0..2] of cint16; {*< Position of the dead zone. } + end; + +{* + * A structure containing a template for a Ramp effect. + * + * This struct is exclusively for the SDL_HAPTIC_RAMP effect. + * + * The ramp effect starts at start strength and ends at end strength. It + * augments in linear fashion. If you use attack and fade with a ramp the + * effects get added to the ramp effect making the effect become quadratic + * instead of linear. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_HAPTIC_RAMP + * \sa SDL_HapticEffect + } +type + PPSDL_HapticRamp = ^PSDL_HapticRamp; + PSDL_HapticRamp = ^TSDL_HapticRamp; + TSDL_HapticRamp = record + { Header } + type_: cuint16; {*< SDL_HAPTIC_RAMP } + direction: TSDL_HapticDirection; {*< Direction of the effect. } + + { Replay } + length: cuint32; {*< Duration of the effect. } + delay: cuint16; {*< Delay before starting the effect. } + + { Trigger } + button: cuint16; {*< Button that triggers the effect. } + interval: cuint16; {*< How soon it can be triggered again after button. } + + { Ramp } + start: cint16; {*< Beginning strength level. } + end_: cint16; {*< Ending strength level. } + + { Envelope } + attack_length: cuint16; {*< Duration of the attack. } + attack_level: cuint16; {*< Level at the start of the attack. } + fade_length: cuint16; {*< Duration of the fade. } + fade_level: cuint16; {*< Level at the end of the fade. } + end; + +{* + * A structure containing a template for a Left/Right effect. + * + * This struct is exclusively for the SDL_HAPTIC_LEFTRIGHT effect. + * + * The Left/Right effect is used to explicitly control the large and small + * motors, commonly found in modern game controllers. The small (right) motor + * is high frequency, and the large (left) motor is low frequency. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_HAPTIC_LEFTRIGHT + * \sa SDL_HapticEffect + } +type + PPSDL_HapticLeftRight = ^PSDL_HapticLeftRight; + PSDL_HapticLeftRight = ^TSDL_HapticLeftRight; + TSDL_HapticLeftRight = record + { Header } + type_: cuint16; {*< SDL_HAPTIC_LEFTRIGHT } + + { Replay } + length: cuint32; {*< Duration of the effect in milliseconds. } + + { Rumble } + large_magnitude: cuint16; {*< Control of the large controller motor. } + small_magnitude: cuint16; {*< Control of the small controller motor. } + end; + +{* + * A structure containing a template for the SDL_HAPTIC_CUSTOM effect. + * + * This struct is exclusively for the SDL_HAPTIC_CUSTOM effect. + * + * A custom force feedback effect is much like a periodic effect, where the + * application can define its exact shape. You will have to allocate the data + * yourself. Data should consist of channels * samples Uint16 samples. + * + * If channels is one, the effect is rotated using the defined direction. + * Otherwise it uses the samples in data for the different axes. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_HAPTIC_CUSTOM + * \sa SDL_HapticEffect + } +type + PPSDL_HapticCustom = ^PSDL_HapticCustom; + PSDL_HapticCustom = ^TSDL_HapticCustom; + TSDL_HapticCustom = record + { Header } + type_: cuint16; {*< SDL_HAPTIC_CUSTOM } + direction: TSDL_HapticDirection; {*< Direction of the effect. } + + { Replay } + length: cuint32; {*< Duration of the effect. } + delay: cuint16; {*< Delay before starting the effect. } + + { Trigger } + button: cuint16; {*< Button that triggers the effect. } + interval: cuint16; {*< How soon it can be triggered again after button. } + + { Custom } + channels: cuint8; {*< Axes to use, minimum of one. } + period: cuint16; {*< Sample periods. } + samples: cuint16; {*< Amount of samples. } + data: pcuint16; {*< Should contain channels*samples items. } + + { Envelope } + attack_length: cuint16; {*< Duration of the attack. } + attack_level: cuint16; {*< Level at the start of the attack. } + fade_length: cuint16; {*< Duration of the fade. } + fade_level: cuint16; {*< Level at the end of the fade. } + end; + +{* + * The generic template for any haptic effect. + * + * All values max at 32767 (0x7FFF). Signed values also can be negative. Time + * values unless specified otherwise are in milliseconds. + * + * You can also pass SDL_HAPTIC_INFINITY to length instead of a 0-32767 value. + * Neither delay, interval, attack_length nor fade_length support + * SDL_HAPTIC_INFINITY. Fade will also not be used since effect never ends. + * + * Additionally, the SDL_HAPTIC_RAMP effect does not support a duration of + * SDL_HAPTIC_INFINITY. + * + * Button triggers may not be supported on all devices, it is advised to not + * use them if possible. Buttons start at index 1 instead of index 0 like the + * joystick. + * + * If both attack_length and fade_level are 0, the envelope is not used, + * otherwise both values are used. + * + * Common parts: + * + * ```c + * // Replay - All effects have this + * Uint32 length; // Duration of effect (ms). + * Uint16 delay; // Delay before starting effect. + * + * // Trigger - All effects have this + * Uint16 button; // Button that triggers effect. + * Uint16 interval; // How soon before effect can be triggered again. + * + * // Envelope - All effects except condition effects have this + * Uint16 attack_length; // Duration of the attack (ms). + * Uint16 attack_level; // Level at the start of the attack. + * Uint16 fade_length; // Duration of the fade out (ms). + * Uint16 fade_level; // Level at the end of the fade. + * ``` + * + * Here we have an example of a constant effect evolution in time: + * + * ``` + * Strength + * ^ + * | + * | effect level --> _________________ + * | / \ + * | / \ + * | / \ + * | / \ + * | attack_level --> | \ + * | | | <--- fade_level + * | + * +--------------------------------------------------> Time + * [--] [---] + * attack_length fade_length + * + * [------------------][-----------------------] + * delay length + * ``` + * + * Note either the attack_level or the fade_level may be above the actual + * effect level. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_HapticConstant + * \sa SDL_HapticPeriodic + * \sa SDL_HapticCondition + * \sa SDL_HapticRamp + * \sa SDL_HapticLeftRight + * \sa SDL_HapticCustom + } +type + PPSDL_HapticEffect = ^PSDL_HapticEffect; + PSDL_HapticEffect = ^TSDL_HapticEffect; + TSDL_HapticEffect = record + { Common for all force feedback effects } + case Integer of + 0: (type_: cuint16); {*< Effect type. } + 1: (constant: TSDL_HapticConstant); {*< Constant effect. } + 2: (periodic: TSDL_HapticPeriodic); {*< Periodic effect. } + 3: (condition: TSDL_HapticCondition); {*< Condition effect. } + 4: (ramp: TSDL_HapticRamp); {*< Ramp effect. } + 5: (leftright: TSDL_HapticLeftRight); {*< Left/Right effect. } + 6: (custom: TSDL_HapticCustom); {*< Custom effect. } + end; + +{* + * This is a unique ID for a haptic device for the time it is connected to the + * system, and is never reused for the lifetime of the application. + * + * If the haptic device is disconnected and reconnected, it will get a new ID. + * + * The value 0 is an invalid ID. + * + * \since This datatype is available since SDL 3.2.0. + } +type + PPSDL_HapticID = ^PSDL_HapticID; + PSDL_HapticID = ^TSDL_HapticID; + TSDL_HapticID = type cuint32; + +{ Function prototypes } + +{* + * Get a list of currently connected haptic devices. + * + * \param count a Pointer filled in with the number of haptic devices + * returned, may be nil. + * \returns a 0 terminated array of haptic device instance IDs or nil on + * failure; call SDL_GetError() for more information. This should be + * freed with SDL_free() when it is no longer needed. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenHaptic + } +function SDL_GetHaptics(count: pcint): PSDL_HapticID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetHaptics' {$ENDIF} {$ENDIF}; + +{* + * Get the implementation dependent name of a haptic device. + * + * This can be called before any haptic devices are opened. + * + * \param instance_id the haptic device instance ID. + * \returns the name of the selected haptic device. If no name can be found, + * this function returns nil; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetHapticName + * \sa SDL_OpenHaptic + } +function SDL_GetHapticNameForID(instance_id: TSDL_HapticID): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetHapticNameForID' {$ENDIF} {$ENDIF}; + +{* + * Open a haptic device for use. + * + * The index passed as an argument refers to the N'th haptic device on this + * system. + * + * When opening a haptic device, its gain will be set to maximum and + * autocenter will be disabled. To modify these values use SDL_SetHapticGain() + * and SDL_SetHapticAutocenter(). + * + * \param instance_id the haptic device instance ID. + * \returns the device identifier or nil on failure; call SDL_GetError() for + * more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseHaptic + * \sa SDL_GetHaptics + * \sa SDL_OpenHapticFromJoystick + * \sa SDL_OpenHapticFromMouse + * \sa SDL_SetHapticAutocenter + * \sa SDL_SetHapticGain + } +function SDL_OpenHaptic(instance_id: TSDL_HapticID): PSDL_Haptic; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_OpenHaptic' {$ENDIF} {$ENDIF}; + +{* + * Get the SDL_Haptic associated with an instance ID, if it has been opened. + * + * \param instance_id the instance ID to get the SDL_Haptic for. + * \returns an SDL_Haptic on success or nil on failure or if it hasn't been + * opened yet; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetHapticFromID(instance_id: TSDL_HapticID): PSDL_Haptic; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetHapticFromID' {$ENDIF} {$ENDIF}; + +{* + * Get the instance ID of an opened haptic device. + * + * \param haptic the SDL_Haptic device to query. + * \returns the instance ID of the specified haptic device on success or 0 on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetHapticID(haptic: PSDL_Haptic): TSDL_HapticID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetHapticID' {$ENDIF} {$ENDIF}; + +{* + * Get the implementation dependent name of a haptic device. + * + * \param haptic the SDL_Haptic obtained from SDL_OpenJoystick(). + * \returns the name of the selected haptic device. If no name can be found, + * this function returns nil; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetHapticNameForID + } +function SDL_GetHapticName(haptic: PSDL_Haptic): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetHapticName' {$ENDIF} {$ENDIF}; + +{* + * Query whether or not the current mouse has haptic capabilities. + * + * \returns true if the mouse is haptic or false if it isn't. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenHapticFromMouse + } +function SDL_IsMouseHaptic: cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IsMouseHaptic' {$ENDIF} {$ENDIF}; + +{* + * Try to open a haptic device from the current mouse. + * + * \returns the haptic device identifier or nil on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseHaptic + * \sa SDL_IsMouseHaptic + } +function SDL_OpenHapticFromMouse: PSDL_Haptic; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_OpenHapticFromMouse' {$ENDIF} {$ENDIF}; + +{* + * Query if a joystick has haptic features. + * + * \param joystick the SDL_Joystick to test for haptic capabilities. + * \returns true if the joystick is haptic or false if it isn't. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenHapticFromJoystick + } +function SDL_IsJoystickHaptic(joystick: PSDL_Joystick): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IsJoystickHaptic' {$ENDIF} {$ENDIF}; + +{* + * Open a haptic device for use from a joystick device. + * + * You must still close the haptic device separately. It will not be closed + * with the joystick. + * + * When opened from a joystick you should first close the haptic device before + * closing the joystick device. If not, on some implementations the haptic + * device will also get unallocated and you'll be unable to use force feedback + * on that device. + * + * \param joystick the SDL_Joystick to create a haptic device from. + * \returns a valid haptic device identifier on success or nil on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseHaptic + * \sa SDL_IsJoystickHaptic + } +function SDL_OpenHapticFromJoystick(joystick: PSDL_Joystick): PSDL_Haptic; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_OpenHapticFromJoystick' {$ENDIF} {$ENDIF}; + +{* + * Close a haptic device previously opened with SDL_OpenHaptic(). + * + * \param haptic the SDL_Haptic device to close. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenHaptic + } +procedure SDL_CloseHaptic(haptic: PSDL_Haptic); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CloseHaptic' {$ENDIF} {$ENDIF}; + +{* + * Get the number of effects a haptic device can store. + * + * On some platforms this isn't fully supported, and therefore is an + * approximation. Always check to see if your created effect was actually + * created and do not rely solely on SDL_GetMaxHapticEffects(). + * + * \param haptic the SDL_Haptic device to query. + * \returns the number of effects the haptic device can store or a negative + * error code on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetMaxHapticEffectsPlaying + * \sa SDL_GetHapticFeatures + } +function SDL_GetMaxHapticEffects(haptic: PSDL_Haptic): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetMaxHapticEffects' {$ENDIF} {$ENDIF}; + +{* + * Get the number of effects a haptic device can play at the same time. + * + * This is not supported on all platforms, but will always return a value. + * + * \param haptic the SDL_Haptic device to query maximum playing effects. + * \returns the number of effects the haptic device can play at the same time + * or -1 on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetMaxHapticEffects + * \sa SDL_GetHapticFeatures + } +function SDL_GetMaxHapticEffectsPlaying(haptic: PSDL_Haptic): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetMaxHapticEffectsPlaying' {$ENDIF} {$ENDIF}; + +{* + * Get the haptic device's supported features in bitwise manner. + * + * \param haptic the SDL_Haptic device to query. + * \returns a list of supported haptic features in bitwise manner (OR'd), or 0 + * on failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_HapticEffectSupported + * \sa SDL_GetMaxHapticEffects + } +function SDL_GetHapticFeatures(haptic: PSDL_Haptic): cuint32; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetHapticFeatures' {$ENDIF} {$ENDIF}; + +{* + * Get the number of haptic axes the device has. + * + * The number of haptic axes might be useful if working with the + * SDL_HapticDirection effect. + * + * \param haptic the SDL_Haptic device to query. + * \returns the number of axes on success or -1 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetNumHapticAxes(haptic: PSDL_Haptic): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetNumHapticAxes' {$ENDIF} {$ENDIF}; + +{* + * Check to see if an effect is supported by a haptic device. + * + * \param haptic the SDL_Haptic device to query. + * \param effect the desired effect to query. + * \returns true if the effect is supported or false if it isn't. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateHapticEffect + * \sa SDL_GetHapticFeatures + } +function SDL_HapticEffectSupported(haptic: PSDL_Haptic; effect: PSDL_HapticEffect): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticEffectSupported' {$ENDIF} {$ENDIF}; + +{* + * Create a new haptic effect on a specified device. + * + * \param haptic an SDL_Haptic device to create the effect on. + * \param effect an SDL_HapticEffect structure containing the properties of + * the effect to create. + * \returns the ID of the effect on success or -1 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyHapticEffect + * \sa SDL_RunHapticEffect + * \sa SDL_UpdateHapticEffect + } +function SDL_CreateHapticEffect(haptic: PSDL_Haptic; effect: PSDL_HapticEffect): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateHapticEffect' {$ENDIF} {$ENDIF}; + +{* + * Update the properties of an effect. + * + * Can be used dynamically, although behavior when dynamically changing + * direction may be strange. Specifically the effect may re-upload itself and + * start playing from the start. You also cannot change the type either when + * running SDL_UpdateHapticEffect(). + * + * \param haptic the SDL_Haptic device that has the effect. + * \param effect the identifier of the effect to update. + * \param data an SDL_HapticEffect structure containing the new effect + * properties to use. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateHapticEffect + * \sa SDL_RunHapticEffect + } +function SDL_UpdateHapticEffect(haptic: PSDL_Haptic; effect: cint; data: PSDL_HapticEffect): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UpdateHapticEffect' {$ENDIF} {$ENDIF}; + +{* + * Run the haptic effect on its associated haptic device. + * + * To repeat the effect over and over indefinitely, set `iterations` to + * `SDL_HAPTIC_INFINITY`. (Repeats the envelope - attack and fade.) To make + * one instance of the effect last indefinitely (so the effect does not fade), + * set the effect's `length` in its structure/union to `SDL_HAPTIC_INFINITY` + * instead. + * + * \param haptic the SDL_Haptic device to run the effect on. + * \param effect the ID of the haptic effect to run. + * \param iterations the number of iterations to run the effect; use + * `SDL_HAPTIC_INFINITY` to repeat forever. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetHapticEffectStatus + * \sa SDL_StopHapticEffect + * \sa SDL_StopHapticEffects + } +function SDL_RunHapticEffect(haptic: PSDL_Haptic; effect: cint; iterations: cuint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RunHapticEffect' {$ENDIF} {$ENDIF}; + +{* + * Stop the haptic effect on its associated haptic device. + * + * \param haptic the SDL_Haptic device to stop the effect on. + * \param effect the ID of the haptic effect to stop. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RunHapticEffect + * \sa SDL_StopHapticEffects + } +function SDL_StopHapticEffect(haptic: PSDL_Haptic; effect: cint): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_StopHapticEffect' {$ENDIF} {$ENDIF}; + +{* + * Destroy a haptic effect on the device. + * + * This will stop the effect if it's running. Effects are automatically + * destroyed when the device is closed. + * + * \param haptic the SDL_Haptic device to destroy the effect on. + * \param effect the ID of the haptic effect to destroy. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateHapticEffect + } +procedure SDL_DestroyHapticEffect(haptic: PSDL_Haptic; effect: cint); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DestroyHapticEffect' {$ENDIF} {$ENDIF}; + +{* + * Get the status of the current effect on the specified haptic device. + * + * Device must support the SDL_HAPTIC_STATUS feature. + * + * \param haptic the SDL_Haptic device to query for the effect status on. + * \param effect the ID of the haptic effect to query its status. + * \returns true if it is playing, false if it isn't playing or haptic status + * isn't supported. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetHapticFeatures + } +function SDL_GetHapticEffectStatus(haptic: PSDL_Haptic; effect: cint): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetHapticEffectStatus' {$ENDIF} {$ENDIF}; + +{* + * Set the global gain of the specified haptic device. + * + * Device must support the SDL_HAPTIC_GAIN feature. + * + * The user may specify the maximum gain by setting the environment variable + * `SDL_HAPTIC_GAIN_MAX` which should be between 0 and 100. All calls to + * SDL_SetHapticGain() will scale linearly using `SDL_HAPTIC_GAIN_MAX` as the + * maximum. + * + * \param haptic the SDL_Haptic device to set the gain on. + * \param gain value to set the gain to, should be between 0 and 100 (0 - + * 100). + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetHapticFeatures + } +function SDL_SetHapticGain(haptic: PSDL_Haptic; gain: cint): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetHapticGain' {$ENDIF} {$ENDIF}; + +{* + * Set the global autocenter of the device. + * + * Autocenter should be between 0 and 100. Setting it to 0 will disable + * autocentering. + * + * Device must support the SDL_HAPTIC_AUTOCENTER feature. + * + * \param haptic the SDL_Haptic device to set autocentering on. + * \param autocenter value to set autocenter to (0-100). + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetHapticFeatures + } +function SDL_SetHapticAutocenter(haptic: PSDL_Haptic; autocenter: cint): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetHapticAutocenter' {$ENDIF} {$ENDIF}; + +{* + * Pause a haptic device. + * + * Device must support the `SDL_HAPTIC_PAUSE` feature. Call SDL_ResumeHaptic() + * to resume playback. + * + * Do not modify the effects nor add new ones while the device is paused. That + * can cause all sorts of weird errors. + * + * \param haptic the SDL_Haptic device to pause. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ResumeHaptic + } +function SDL_PauseHaptic(haptic: PSDL_Haptic): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_PauseHaptic' {$ENDIF} {$ENDIF}; + +{* + * Resume a haptic device. + * + * Call to unpause after SDL_PauseHaptic(). + * + * \param haptic the SDL_Haptic device to unpause. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PauseHaptic + } +function SDL_ResumeHaptic(haptic: PSDL_Haptic): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ResumeHaptic' {$ENDIF} {$ENDIF}; + +{* + * Stop all the currently playing effects on a haptic device. + * + * \param haptic the SDL_Haptic device to stop. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RunHapticEffect + * \sa SDL_StopHapticEffects + } +function SDL_StopHapticEffects(haptic: PSDL_Haptic): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_StopHapticEffects' {$ENDIF} {$ENDIF}; + +{* + * Check whether rumble is supported on a haptic device. + * + * \param haptic haptic device to check for rumble support. + * \returns true if the effect is supported or false if it isn't. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InitHapticRumble + } +function SDL_HapticRumbleSupported(haptic: PSDL_Haptic): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HapticRumbleSupported' {$ENDIF} {$ENDIF}; + +{* + * Initialize a haptic device for simple rumble playback. + * + * \param haptic the haptic device to initialize for simple rumble playback. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PlayHapticRumble + * \sa SDL_StopHapticRumble + * \sa SDL_HapticRumbleSupported + } +function SDL_InitHapticRumble(haptic: PSDL_Haptic): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_InitHapticRumble' {$ENDIF} {$ENDIF}; + +{* + * Run a simple rumble effect on a haptic device. + * + * \param haptic the haptic device to play the rumble effect on. + * \param strength strength of the rumble to play as a 0-1 float value. + * \param length length of the rumble to play in milliseconds. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_InitHapticRumble + * \sa SDL_StopHapticRumble + } +function SDL_PlayHapticRumble(haptic: PSDL_Haptic; strength: cfloat; length: cuint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_PlayHapticRumble' {$ENDIF} {$ENDIF}; + +{* + * Stop the simple rumble on a haptic device. + * + * \param haptic the haptic device to stop the rumble effect on. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_PlayHapticRumble + } +function SDL_StopHapticRumble(haptic: PSDL_Haptic): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_StopHapticRumble' {$ENDIF} {$ENDIF}; + From 2233c6f63b0a035756285f0d6dc839af890416f6 Mon Sep 17 00:00:00 2001 From: Matthias Date: Thu, 6 Feb 2025 00:32:24 +0100 Subject: [PATCH 05/18] Add SDL_hidapi.inc --- units/SDL3.pas | 1 + units/SDL_hidapi.inc | 519 +++++++++++++++++++++++++++++++++++++++++++ units/sdl.inc | 1 + 3 files changed, 521 insertions(+) create mode 100644 units/SDL_hidapi.inc diff --git a/units/SDL3.pas b/units/SDL3.pas index 0a02a3c..18fd10a 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -112,6 +112,7 @@ interface {$I SDL_time.inc} // 3.2.0 {$I SDL_filesystem.inc} // 3.2.0 {$I SDL_atomic.inc} // 3.2.0 +{$I SDL_hidapi.inc} // 3.2.0 implementation diff --git a/units/SDL_hidapi.inc b/units/SDL_hidapi.inc new file mode 100644 index 0000000..8958a6a --- /dev/null +++ b/units/SDL_hidapi.inc @@ -0,0 +1,519 @@ +{ + This file is part of: + + SDL3 for Pascal + (https://github.com/PascalGameDevelopment/SDL3-for-Pascal) + SPDX-License-Identifier: Zlib +} + +{* + * # CategoryHIDAPI + * + * Header file for SDL HIDAPI functions. + * + * This is an adaptation of the original HIDAPI interface by Alan Ott, and + * includes source code licensed under the following license: + * + * ``` + * HIDAPI - Multi-Platform library for + * communication with HID devices. + * + * Copyright 2009, Alan Ott, Signal 11 Software. + * All Rights Reserved. + * + * This software may be used by anyone for any reason so + * long as the copyright notice in the source files + * remains intact. + * ``` + * + * (Note that this license is the same as item three of SDL's zlib license, so + * it adds no new requirements on the user.) + * + * If you would like a version of SDL without this code, you can build SDL + * with SDL_HIDAPI_DISABLED defined to 1. You might want to do this for + * example on iOS or tvOS to avoid a dependency on the CoreBluetooth + * framework. + } + +{* + * An opaque handle representing an open HID device. + * + * \since This struct is available since SDL 3.2.0. + } +type + PPSDL_hid_device = ^PSDL_hid_device; + PSDL_hid_device = type Pointer; + +{* + * HID underlying bus types. + * + * \since This enum is available since SDL 3.2.0. + } +type + PPSDL_hid_bus_type = ^PSDL_hid_bus_type; + PSDL_hid_bus_type = ^TSDL_hid_bus_type; + TSDL_hid_bus_type = type Integer; +const + SDL_HID_API_BUS_UNKNOWN = TSDL_hid_bus_type($00); {* Unknown bus type } + SDL_HID_API_BUS_USB = TSDL_hid_bus_type($01); {* USB bus + Specifications: + https://usb.org/hid } + SDL_HID_API_BUS_BLUETOOTH = TSDL_hid_bus_type($02); {* Bluetooth or Bluetooth LE bus + Specifications: + https://www.bluetooth.com/specifications/specs/human-interface-device-profile-1-1-1/ + https://www.bluetooth.com/specifications/specs/hid-service-1-0/ + https://www.bluetooth.com/specifications/specs/hid-over-gatt-profile-1-0/ } + SDL_HID_API_BUS_I2C = TSDL_hid_bus_type($03); {* I2C bus + Specifications: + https://docs.microsoft.com/previous-versions/windows/hardware/design/dn642101(v=vs.85) } + SDL_HID_API_BUS_SPI = TSDL_hid_bus_type($04); {* SPI bus + Specifications: + https://www.microsoft.com/download/details.aspx?id=103325 } + +{* hidapi info structure } + +{* + * Information about a connected HID device + * + * \since This struct is available since SDL 3.2.0. + } +type + PPSDL_hid_device_info = ^PSDL_hid_device_info; + PSDL_hid_device_info = ^TSDL_hid_device_info; + TSDL_hid_device_info = record + path: PAnsiChar; {* Platform-specific device path } + vendor_id: cushort; {* Device Vendor ID } + product_id: cushort; {* Device Product ID } + serial_number: cwchar_t; {* Serial Number } + release_number: cushort; {* Device Release Number in binary-coded decimal, + also known as Device Version Number } + manufacturer_string: cwchar_t; {* Manufacturer String } + product_string: cwchar_t; {* Product string } + usage_page: cushort; {* Usage Page for this Device/Interface + (Windows/Mac/hidraw only) } + usage: cushort; {* Usage for this Device/Interface + (Windows/Mac/hidraw only) } + interface_number: cint; {* The USB interface which this logical device + represents. + + Valid only if the device is a USB HID device. + Set to -1 in all other cases. + } + interface_class: cint; {* Additional information about the USB interface. + Valid on libusb and Android implementations. } + interface_subclass: cint; + interface_protocol: cint; + bus_type: TSDL_hid_bus_type; {* Underlying bus type } + next: PSDL_hid_device_info; {* Pointer to the next device } + end; + +{* + * Initialize the HIDAPI library. + * + * This function initializes the HIDAPI library. Calling it is not strictly + * necessary, as it will be called automatically by SDL_hid_enumerate() and + * any of the SDL_hid_open_*() functions if it is needed. This function should + * be called at the beginning of execution however, if there is a chance of + * HIDAPI handles being opened by different threads simultaneously. + * + * Each call to this function should have a matching call to SDL_hid_exit() + * + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_hid_exit + } +function SDL_hid_init: cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_init' {$ENDIF} {$ENDIF}; + +{* + * Finalize the HIDAPI library. + * + * This function frees all of the static data associated with HIDAPI. It + * should be called at the end of execution to avoid memory leaks. + * + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_hid_init + } +function SDL_hid_exit: cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_exit' {$ENDIF} {$ENDIF}; + +{* + * Check to see if devices may have been added or removed. + * + * Enumerating the HID devices is an expensive operation, so you can call this + * to see if there have been any system device changes since the last call to + * this function. A change in the counter returned doesn't necessarily mean + * that anything has changed, but you can call SDL_hid_enumerate() to get an + * updated device list. + * + * Calling this function for the first time may cause a thread or other system + * resource to be allocated to track device change notifications. + * + * \returns a change counter that is incremented with each potential device + * change, or 0 if device change detection isn't available. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_hid_enumerate + } +function SDL_hid_device_change_count: cuint32; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_device_change_count' {$ENDIF} {$ENDIF}; + +{* + * Enumerate the HID Devices. + * + * This function returns a linked list of all the HID devices attached to the + * system which match vendor_id and product_id. If `vendor_id` is set to 0 + * then any vendor matches. If `product_id` is set to 0 then any product + * matches. If `vendor_id` and `product_id` are both set to 0, then all HID + * devices will be returned. + * + * By default SDL will only enumerate controllers, to reduce risk of hanging + * or crashing on bad drivers, but SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS + * can be set to "0" to enumerate all HID devices. + * + * \param vendor_id the Vendor ID (VID) of the types of device to open, or 0 + * to match any vendor. + * \param product_id the Product ID (PID) of the types of device to open, or 0 + * to match any product. + * \returns a Pointer to a linked list of type SDL_hid_device_info, containing + * information about the HID devices attached to the system, or nil + * in the case of failure. Free this linked list by calling + * SDL_hid_free_enumeration(). + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_hid_device_change_count + } +function SDL_hid_enumerate(vendor_id: cushort; product_id: cushort): PSDL_hid_device_info; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_enumerate' {$ENDIF} {$ENDIF}; + +{* + * Free an enumeration linked list. + * + * This function frees a linked list created by SDL_hid_enumerate(). + * + * \param devs Pointer to a list of struct_device returned from + * SDL_hid_enumerate(). + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_hid_free_enumeration(devs: PSDL_hid_device_info); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_free_enumeration' {$ENDIF} {$ENDIF}; + +{* + * Open a HID device using a Vendor ID (VID), Product ID (PID) and optionally + * a serial number. + * + * If `serial_number` is nil, the first device with the specified VID and PID + * is opened. + * + * \param vendor_id the Vendor ID (VID) of the device to open. + * \param product_id the Product ID (PID) of the device to open. + * \param serial_number the Serial Number of the device to open (Optionally + * nil). + * \returns a Pointer to a SDL_hid_device object on success or nil on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_hid_open(vendor_id: cushort; product_id: cushort; serial_number: pcwchar_t): PSDL_hid_device; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_open' {$ENDIF} {$ENDIF}; + +{* + * Open a HID device by its path name. + * + * The path name be determined by calling SDL_hid_enumerate(), or a + * platform-specific path name can be used (eg: /dev/hidraw0 on Linux). + * + * \param path the path name of the device to open. + * \returns a Pointer to a SDL_hid_device object on success or nil on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_hid_open_path(path: PAnsiChar): PSDL_hid_device; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_open_path' {$ENDIF} {$ENDIF}; + +{* + * Write an Output report to a HID device. + * + * The first byte of `data` must contain the Report ID. For devices which only + * support a single report, this must be set to 0x0. The remaining bytes + * contain the report data. Since the Report ID is mandatory, calls to + * SDL_hid_write() will always contain one more byte than the report contains. + * For example, if a hid report is 16 bytes long, 17 bytes must be passed to + * SDL_hid_write(), the Report ID (or 0x0, for devices with a single report), + * followed by the report data (16 bytes). In this example, the length passed + * in would be 17. + * + * SDL_hid_write() will send the data on the first OUT endpoint, if one + * exists. If it does not, it will send the data through the Control Endpoint + * (Endpoint 0). + * + * \param dev a device handle returned from SDL_hid_open(). + * \param data the data to send, including the report number as the first + * byte. + * \param length the length in bytes of the data to send. + * \returns the actual number of bytes written and -1 on on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_hid_write(dev: PSDL_hid_device; data: pcuchar; length: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_write' {$ENDIF} {$ENDIF}; + +{* + * Read an Input report from a HID device with timeout. + * + * Input reports are returned to the host through the INTERRUPT IN endpoint. + * The first byte will contain the Report number if the device uses numbered + * reports. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param data a buffer to put the read data into. + * \param length the number of bytes to read. For devices with multiple + * reports, make sure to read an extra byte for the report + * number. + * \param milliseconds timeout in milliseconds or -1 for blocking wait. + * \returns the actual number of bytes read and -1 on on failure; call + * SDL_GetError() for more information. If no packet was available to + * be read within the timeout period, this function returns 0. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_hid_read_timeout(dev: PSDL_hid_device; data: pcuchar; length: csize_t; milliseconds: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_read_timeout' {$ENDIF} {$ENDIF}; + +{* + * Read an Input report from a HID device. + * + * Input reports are returned to the host through the INTERRUPT IN endpoint. + * The first byte will contain the Report number if the device uses numbered + * reports. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param data a buffer to put the read data into. + * \param length the number of bytes to read. For devices with multiple + * reports, make sure to read an extra byte for the report + * number. + * \returns the actual number of bytes read and -1 on failure; call + * SDL_GetError() for more information. If no packet was available to + * be read and the handle is in non-blocking mode, this function + * returns 0. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_hid_read(dev: PSDL_hid_device; data: pcuchar; length: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_read' {$ENDIF} {$ENDIF}; + +{* + * Set the device handle to be non-blocking. + * + * In non-blocking mode calls to SDL_hid_read() will return immediately with a + * value of 0 if there is no data to be read. In blocking mode, SDL_hid_read() + * will wait (block) until there is data to read before returning. + * + * Nonblocking can be turned on and off at any time. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param nonblock enable or not the nonblocking reads - 1 to enable + * nonblocking - 0 to disable nonblocking. + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_hid_set_nonblocking(dev: PSDL_hid_device; nonblock: cint): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_set_nonblocking' {$ENDIF} {$ENDIF}; + +{* + * Send a Feature report to the device. + * + * Feature reports are sent over the Control endpoint as a Set_Report + * transfer. The first byte of `data` must contain the Report ID. For devices + * which only support a single report, this must be set to 0x0. The remaining + * bytes contain the report data. Since the Report ID is mandatory, calls to + * SDL_hid_send_feature_report() will always contain one more byte than the + * report contains. For example, if a hid report is 16 bytes long, 17 bytes + * must be passed to SDL_hid_send_feature_report(): the Report ID (or 0x0, for + * devices which do not use numbered reports), followed by the report data (16 + * bytes). In this example, the length passed in would be 17. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param data the data to send, including the report number as the first + * byte. + * \param length the length in bytes of the data to send, including the report + * number. + * \returns the actual number of bytes written and -1 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_hid_send_feature_report(dev: PSDL_hid_device; data: pcuchar; length: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_send_feature_report' {$ENDIF} {$ENDIF}; + +{* + * Get a feature report from a HID device. + * + * Set the first byte of `data` to the Report ID of the report to be read. + * Make sure to allow space for this extra byte in `data`. Upon return, the + * first byte will still contain the Report ID, and the report data will start + * in data[1]. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param data a buffer to put the read data into, including the Report ID. + * Set the first byte of `data` to the Report ID of the report to + * be read, or set it to zero if your device does not use numbered + * reports. + * \param length the number of bytes to read, including an extra byte for the + * report ID. The buffer can be longer than the actual report. + * \returns the number of bytes read plus one for the report ID (which is + * still in the first byte), or -1 on on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_hid_get_feature_report(dev: PSDL_hid_device; data: pcuchar; length: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_get_feature_report' {$ENDIF} {$ENDIF}; + +{* + * Get an input report from a HID device. + * + * Set the first byte of `data` to the Report ID of the report to be read. + * Make sure to allow space for this extra byte in `data`. Upon return, the + * first byte will still contain the Report ID, and the report data will start + * in data[1]. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param data a buffer to put the read data into, including the Report ID. + * Set the first byte of `data` to the Report ID of the report to + * be read, or set it to zero if your device does not use numbered + * reports. + * \param length the number of bytes to read, including an extra byte for the + * report ID. The buffer can be longer than the actual report. + * \returns the number of bytes read plus one for the report ID (which is + * still in the first byte), or -1 on on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_hid_get_input_report(dev: PSDL_hid_device; data: pcuchar; length: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_get_input_report' {$ENDIF} {$ENDIF}; + +{* + * Close a HID device. + * + * \param dev a device handle returned from SDL_hid_open(). + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_hid_close(dev: PSDL_hid_device): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_close' {$ENDIF} {$ENDIF}; + +{* + * Get The Manufacturer String from a HID device. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param string a wide string buffer to put the data into. + * \param maxlen the length of the buffer in multiples of wchar_t. + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_hid_get_manufacturer_string(dev: PSDL_hid_device; _string: pcwchar_t; maxlen: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_get_manufacturer_string' {$ENDIF} {$ENDIF}; + +{* + * Get The Product String from a HID device. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param string a wide string buffer to put the data into. + * \param maxlen the length of the buffer in multiples of wchar_t. + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_hid_get_product_string(dev: PSDL_hid_device; _string: pcwchar_t; maxlen: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_get_product_string' {$ENDIF} {$ENDIF}; + +{* + * Get The Serial Number String from a HID device. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param string a wide string buffer to put the data into. + * \param maxlen the length of the buffer in multiples of wchar_t. + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_hid_get_serial_number_string(dev: PSDL_hid_device; _string: pcwchar_t; maxlen: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_get_serial_number_string' {$ENDIF} {$ENDIF}; + +{* + * Get a string from a HID device, based on its string index. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param string_index the index of the string to get. + * \param string a wide string buffer to put the data into. + * \param maxlen the length of the buffer in multiples of wchar_t. + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_hid_get_indexed_string(dev: PSDL_hid_device; string_index: cint; _string: pcwchar_t; maxlen: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_get_indexed_string' {$ENDIF} {$ENDIF}; + +{* + * Get the device info from a HID device. + * + * \param dev a device handle returned from SDL_hid_open(). + * \returns a Pointer to the SDL_hid_device_info for this hid_device or nil + * on failure; call SDL_GetError() for more information. This struct + * is valid until the device is closed with SDL_hid_close(). + * + * \since This function is available since SDL 3.2.0. + } +function SDL_hid_get_device_info(dev: PSDL_hid_device): PSDL_hid_device_info; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_get_device_info' {$ENDIF} {$ENDIF}; + +{* + * Get a report descriptor from a HID device. + * + * User has to provide a preallocated buffer where descriptor will be copied + * to. The recommended size for a preallocated buffer is 4096 bytes. + * + * \param dev a device handle returned from SDL_hid_open(). + * \param buf the buffer to copy descriptor into. + * \param buf_size the size of the buffer in bytes. + * \returns the number of bytes actually copied or -1 on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_hid_get_report_descriptor(dev: PSDL_hid_device; buf: pcuchar; buf_size: csize_t): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_get_report_descriptor' {$ENDIF} {$ENDIF}; + +{* + * Start or stop a BLE scan on iOS and tvOS to pair Steam Controllers. + * + * \param active true to start the scan, false to stop the scan. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_hid_ble_scan(active: cbool); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_hid_ble_scan' {$ENDIF} {$ENDIF}; + diff --git a/units/sdl.inc b/units/sdl.inc index 2d6463f..b900529 100644 --- a/units/sdl.inc +++ b/units/sdl.inc @@ -9,3 +9,4 @@ { Compiler defines } {$DEFINE SDL} // define "SDL" symbol +{$DEFINE WANT_CWCHAR_T} // define C's wchar_t types From 17f4b4c48853411cba9b7a6434ee1242f3005f93 Mon Sep 17 00:00:00 2001 From: Matthias Date: Thu, 6 Feb 2025 10:20:46 +0100 Subject: [PATCH 06/18] Finish SDL_iostream.inc --- units/SDL3.pas | 2 +- units/SDL_iostream.inc | 1350 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1351 insertions(+), 1 deletion(-) diff --git a/units/SDL3.pas b/units/SDL3.pas index 18fd10a..72906f6 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -85,7 +85,7 @@ interface {$I SDL_properties.inc} // 3.1.6-prev {$I SDL_pixels.inc} // 3.1.6-prev {$I SDL_blendmode.inc} // 3.1.6-prev -{$I SDL_iostream.inc} // 3.1.6-prev (unfinished) +{$I SDL_iostream.inc} // 3.2.0 {$I SDL_surface.inc} // 3.1.6-prev {$I SDL_video.inc} // 3.1.6-prev {$I SDL_timer.inc} // 3.1.6-prev diff --git a/units/SDL_iostream.inc b/units/SDL_iostream.inc index 64cb5d4..2747ada 100644 --- a/units/SDL_iostream.inc +++ b/units/SDL_iostream.inc @@ -6,6 +6,146 @@ SPDX-License-Identifier: Zlib } +{* + * # CategoryIOStream + * + * SDL provides an abstract interface for reading and writing data streams. It + * offers implementations for files, memory, etc, and the app can provide + * their own implementations, too. + * + * SDL_IOStream is not related to the standard C++ iostream class, other than + * both are abstract interfaces to read/write data. + } + +{* + * SDL_IOStream status, set by a read or write operation. + * + * \since This enum is available since SDL 3.2.0. + } +type + PPSDL_IOStatus = ^PSDL_IOStatus; + PSDL_IOStatus = ^TSDL_IOStatus; + TSDL_IOStatus = type Integer; +const + SDL_IO_STATUS_READY = TSDL_IOStatus(0); {*< Everything is ready (no errors and not EOF). } + SDL_IO_STATUS_ERROR = TSDL_IOStatus(1); {*< Read or write I/O error } + SDL_IO_STATUS_EOF = TSDL_IOStatus(2); {*< End of file } + SDL_IO_STATUS_NOT_READY = TSDL_IOStatus(3); {*< Non blocking I/O, not ready } + SDL_IO_STATUS_READONLY = TSDL_IOStatus(4); {*< Tried to write a read-only buffer } + SDL_IO_STATUS_WRITEONLY = TSDL_IOStatus(5); {*< Tried to read a write-only buffer } + +{* + * Possible `whence` values for SDL_IOStream seeking. + * + * These map to the same "whence" concept that `fseek` or `lseek` use in the + * standard C runtime. + * + * \since This enum is available since SDL 3.2.0. + } +type + PPSDL_IOWhence = ^PSDL_IOWhence; + PSDL_IOWhence = ^TSDL_IOWhence; + TSDL_IOWhence = type Integer; +const + SDL_IO_SEEK_SET = TSDL_IOWhence(0); {*< Seek from the beginning of data } + SDL_IO_SEEK_CUR = TSDL_IOWhence(1); {*< Seek relative to current read point } + SDL_IO_SEEK_END = TSDL_IOWhence(2); {*< Seek relative to the end of data } + +{* + * The function pointers that drive an SDL_IOStream. + * + * Applications can provide this struct to SDL_OpenIO() to create their own + * implementation of SDL_IOStream. This is not necessarily required, as SDL + * already offers several common types of I/O streams, via functions like + * SDL_IOFromFile() and SDL_IOFromMem(). + * + * This structure should be initialized using SDL_INIT_INTERFACE() + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_INIT_INTERFACE + } +type + PPSDL_IOStreamInterface = ^PSDL_IOStreamInterface; + PSDL_IOStreamInterface = ^TSDL_IOStreamInterface; + TSDL_IOStreamInterface = record + { The version of this interface } + version: cuint32; + + {* + * Return the number of bytes in this SDL_IOStream + * + * \return the total size of the data stream, or -1 on error. + } + size: function (userdata: Pointer): cint64; cdecl; + + {* + * Seek to `offset` relative to `whence`, one of stdio's whence values: + * SDL_IO_SEEK_SET, SDL_IO_SEEK_CUR, SDL_IO_SEEK_END + * + * \return the final offset in the data stream, or -1 on error. + } + seek: function (userdata: Pointer; offset: cint64; whence: TSDL_IOWhence): cint64; cdecl; + + {* + * Read up to `size` bytes from the data stream to the area pointed + * at by `ptr`. + * + * On an incomplete read, you should set `*status` to a value from the + * SDL_IOStatus enum. You do not have to explicitly set this on + * a complete, successful read. + * + * \return the number of bytes read + } + read: function (userdata: Pointer; ptr: Pointer; size: csize_t; status: PSDL_IOStatus): csize_t; cdecl; + + {* + * Write exactly `size` bytes from the area pointed at by `ptr` + * to data stream. + * + * On an incomplete write, you should set `*status` to a value from the + * SDL_IOStatus enum. You do not have to explicitly set this on + * a complete, successful write. + * + * \return the number of bytes written + } + write: function (userdata: Pointer; ptr: Pointer; size: csize_t; status: PSDL_IOStatus): csize_t; cdecl; + + {* + * 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. + } + flush: function (userdata: Pointer; status: PSDL_IOStatus): cbool; cdecl; + + {* + * Close and free any allocated resources. + * + * This does not guarantee file writes will sync to physical media; they + * can be in the system's file cache, waiting to go to disk. + * + * The SDL_IOStream is still destroyed even if this fails, so clean up anything + * even if flushing buffers, etc, returns an error. + * + * \return true if successful or false on write error when flushing data. + } + close: function (userdata: Pointer): cbool; cdecl; + end; + +{ 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. + } +{ +#todo : SDL3-for-Pascal: Implement macro: +SDL_COMPILE_TIME_ASSERT(SDL_IOStreamInterface_SIZE, ... } + {* * The read/write operation structure. * @@ -20,3 +160,1213 @@ type PPSDL_IOStream = ^PSDL_IOStream; PSDL_IOStream = type Pointer; +{* + * \name IOFrom functions + * + * Functions to create SDL_IOStream structures from various data streams. + } + +{* + * Use this function to create a new SDL_IOStream structure for reading from + * and/or writing to a named file. + * + * The `mode` string is treated roughly the same as in a call to the C + * library's fopen(), even if SDL doesn't happen to use fopen() behind the + * scenes. + * + * Available `mode` strings: + * + * - "r": Open a file for reading. The file must exist. + * - "w": Create an empty file for writing. If a file with the same name + * already exists its content is erased and the file is treated as a new + * empty file. + * - "a": Append to a file. Writing operations append data at the end of the + * file. The file is created if it does not exist. + * - "r+": Open a file for update both reading and writing. The file must + * exist. + * - "w+": Create an empty file for both reading and writing. If a file with + * the same name already exists its content is erased and the file is + * treated as a new empty file. + * - "a+": Open a file for reading and appending. All writing operations are + * performed at the end of the file, protecting the previous content to be + * overwritten. You can reposition (fseek, rewind) the internal Pointer to + * anywhere in the file for reading, but writing operations will move it + * back to the end of file. The file is created if it does not exist. + * + * **NOTE**: In order to open a file as a binary file, a "b" character has to + * be included in the `mode` string. This additional "b" character can either + * be appended at the end of the string (thus making the following compound + * modes: "rb", "wb", "ab", "r+b", "w+b", "a+b") or be inserted between the + * letter and the "+" sign for the mixed modes ("rb+", "wb+", "ab+"). + * Additional characters may follow the sequence, although they should have no + * effect. For example, "t" is sometimes appended to make explicit the file is + * a text file. + * + * This function supports Unicode filenames, but they must be encoded in UTF-8 + * format, regardless of the underlying operating system. + * + * In Android, SDL_IOFromFile() can be used to open content:// URIs. As a + * fallback, SDL_IOFromFile() will transparently open a matching filename in + * the app's `assets`. + * + * Closing the SDL_IOStream will close SDL's internal file handle. + * + * The following properties may be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER`: a Pointer, that can be cast + * to a win32 `HANDLE`, that this SDL_IOStream is using to access the + * filesystem. If the program isn't running on Windows, or SDL used some + * other method to access the filesystem, this property will not be set. + * - `SDL_PROP_IOSTREAM_STDIO_FILE_POINTER`: a Pointer, that can be cast to a + * stdio `FILE *`, that this SDL_IOStream is using to access the filesystem. + * If SDL used some other method to access the filesystem, this property + * will not be set. PLEASE NOTE that if SDL is using a different C runtime + * than your app, trying to use this Pointer will almost certainly result in + * a crash! This is mostly a problem on Windows; make sure you build SDL and + * your app with the same compiler and settings to avoid it. + * - `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER`: a file descriptor that this + * SDL_IOStream is using to access the filesystem. + * - `SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER`: a Pointer, that can be cast + * to an Android NDK `AAsset *`, that this SDL_IOStream is using to access + * the filesystem. If SDL used some other method to access the filesystem, + * this property will not be set. + * + * \param file a UTF-8 string representing the filename to open. + * \param mode an ASCII string representing the mode to be used for opening + * the file. + * \returns a Pointer to the SDL_IOStream structure that is created or nil on + * failure; call SDL_GetError() for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseIO + * \sa SDL_FlushIO + * \sa SDL_ReadIO + * \sa SDL_SeekIO + * \sa SDL_TellIO + * \sa SDL_WriteIO + } +function SDL_IOFromFile(file_: PAnsiChar; mode: PAnsiChar): PSDL_IOStream; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IOFromFile' {$ENDIF} {$ENDIF}; + + const + SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER = 'SDL.iostream.windows.handle'; + SDL_PROP_IOSTREAM_STDIO_FILE_POINTER = 'SDL.iostream.stdio.file'; + SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER = 'SDL.iostream.file_descriptor'; + SDL_PROP_IOSTREAM_ANDROID_AASSET_POINTER = 'SDL.iostream.android.aasset'; + +{* + * Use this function to prepare a read-write memory buffer for use with + * SDL_IOStream. + * + * This function sets up an SDL_IOStream struct based on a memory area of a + * certain size, for both read and write access. + * + * This memory buffer is not copied by the SDL_IOStream; the Pointer you + * provide must remain valid until you close the stream. Closing the stream + * will not free the original buffer. + * + * If you need to make sure the SDL_IOStream never writes to the memory + * buffer, you should use SDL_IOFromConstMem() with a read-only buffer of + * memory instead. + * + * The following properties will be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that + * was passed to this function. + * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter + * that was passed to this function. + * + * \param mem a Pointer to a buffer to feed an SDL_IOStream stream. + * \param size the buffer size, in bytes. + * \returns a Pointer to a new SDL_IOStream structure or nil on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_IOFromConstMem + * \sa SDL_CloseIO + * \sa SDL_FlushIO + * \sa SDL_ReadIO + * \sa SDL_SeekIO + * \sa SDL_TellIO + * \sa SDL_WriteIO + } +function SDL_IOFromMem(mem: Pointer; size: csize_t): PSDL_IOStream; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IOFromMem' {$ENDIF} {$ENDIF}; + +const + SDL_PROP_IOSTREAM_MEMORY_POINTER = 'SDL.iostream.memory.base'; + SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER = 'SDL.iostream.memory.size'; + +{* + * Use this function to prepare a read-only memory buffer for use with + * SDL_IOStream. + * + * This function sets up an SDL_IOStream struct based on a memory area of a + * certain size. It assumes the memory area is not writable. + * + * Attempting to write to this SDL_IOStream stream will report an error + * without writing to the memory buffer. + * + * This memory buffer is not copied by the SDL_IOStream; the Pointer you + * provide must remain valid until you close the stream. Closing the stream + * will not free the original buffer. + * + * If you need to write to a memory buffer, you should use SDL_IOFromMem() + * with a writable buffer of memory instead. + * + * The following properties will be set at creation time by SDL: + * + * - `SDL_PROP_IOSTREAM_MEMORY_POINTER`: this will be the `mem` parameter that + * was passed to this function. + * - `SDL_PROP_IOSTREAM_MEMORY_SIZE_NUMBER`: this will be the `size` parameter + * that was passed to this function. + * + * \param mem a Pointer to a read-only buffer to feed an SDL_IOStream stream. + * \param size the buffer size, in bytes. + * \returns a Pointer to a new SDL_IOStream structure or nil on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_IOFromMem + * \sa SDL_CloseIO + * \sa SDL_ReadIO + * \sa SDL_SeekIO + * \sa SDL_TellIO + } +function SDL_IOFromConstMem(mem: Pointer; size: csize_t): PSDL_IOStream; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IOFromConstMem' {$ENDIF} {$ENDIF}; + +{* + * Use this function to create an SDL_IOStream that is backed by dynamically + * allocated memory. + * + * This supports the following properties to provide access to the memory and + * control over allocations: + * + * - `SDL_PROP_IOSTREAM_DYNAMIC_MEMORY_POINTER`: a Pointer to the internal + * memory of the stream. This can be set to nil to transfer ownership of + * the memory to the application, which should free the memory with + * SDL_free(). If this is done, the next operation on the stream must be + * SDL_CloseIO(). + * - `SDL_PROP_IOSTREAM_DYNAMIC_CHUNKSIZE_NUMBER`: memory will be allocated in + * multiples of this size, defaulting to 1024. + * + * \returns a Pointer to a new SDL_IOStream structure or nil on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseIO + * \sa SDL_ReadIO + * \sa SDL_SeekIO + * \sa SDL_TellIO + * \sa SDL_WriteIO + } +function SDL_IOFromDynamicMem: PSDL_IOStream; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IOFromDynamicMem' {$ENDIF} {$ENDIF}; + +const + SDL_PROP_IOSTREAM_DYNAMIC_MEMORY_POINTER = 'SDL.iostream.dynamic.memory'; + SDL_PROP_IOSTREAM_DYNAMIC_CHUNKSIZE_NUMBER = 'SDL.iostream.dynamic.chunksize'; + +{ IOFrom functions } + +{* + * Create a custom SDL_IOStream. + * + * Applications do not need to use this function unless they are providing + * their own SDL_IOStream implementation. If you just need an SDL_IOStream to + * read/write a common data source, you should use the built-in + * implementations in SDL, like SDL_IOFromFile() or SDL_IOFromMem(), etc. + * + * This function makes a copy of `iface` and the caller does not need to keep + * it around after this call. + * + * \param iface the interface that implements this SDL_IOStream, initialized + * using SDL_INIT_INTERFACE(). + * \param userdata the Pointer that will be passed to the interface functions. + * \returns a Pointer to the allocated memory on success or nil on failure; + * call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseIO + * \sa SDL_INIT_INTERFACE + * \sa SDL_IOFromConstMem + * \sa SDL_IOFromFile + * \sa SDL_IOFromMem + } +function SDL_OpenIO(iface: PSDL_IOStreamInterface; userdata: Pointer): PSDL_IOStream; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_OpenIO' {$ENDIF} {$ENDIF}; + +{* + * Close and free an allocated SDL_IOStream structure. + * + * SDL_CloseIO() closes and cleans up the SDL_IOStream stream. It releases any + * resources used by the stream and frees the SDL_IOStream itself. This + * returns true on success, or false if the stream failed to flush to its + * output (e.g. to disk). + * + * Note that if this fails to flush the stream for any reason, this function + * reports an error, but the SDL_IOStream is still invalid once this function + * returns. + * + * This call flushes any buffered writes to the operating system, but there + * are no guarantees that those writes have gone to physical media; they might + * be in the OS's file cache, waiting to go to disk later. If it's absolutely + * crucial that writes go to disk immediately, so they are definitely stored + * even if the power fails before the file cache would have caught up, one + * should call SDL_FlushIO() before closing. Note that flushing takes time and + * makes the system and your app operate less efficiently, so do so sparingly. + * + * \param context SDL_IOStream structure to close. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenIO + } +function SDL_CloseIO(context: PSDL_IOStream): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CloseIO' {$ENDIF} {$ENDIF}; + +{* + * Get the properties associated with an SDL_IOStream. + * + * \param context a Pointer to an SDL_IOStream structure. + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetIOProperties(context: PSDL_IOStream): TSDL_PropertiesID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetIOProperties' {$ENDIF} {$ENDIF}; + +{* + * Query the stream status of an SDL_IOStream. + * + * This information can be useful to decide if a short read or write was due + * to an error, an EOF, or a non-blocking operation that isn't yet ready to + * complete. + * + * An SDL_IOStream's status is only expected to change after a SDL_ReadIO or + * SDL_WriteIO call; don't expect it to change if you just call this query + * function in a tight loop. + * + * \param context the SDL_IOStream to query. + * \returns an SDL_IOStatus enum with the current state. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetIOStatus(context: PSDL_IOStream): TSDL_IOStatus; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetIOStatus' {$ENDIF} {$ENDIF}; + +{* + * Use this function to get the size of the data stream in an SDL_IOStream. + * + * \param context the SDL_IOStream to get the size of the data stream from. + * \returns the size of the data stream in the SDL_IOStream on success or a + * negative error code on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetIOSize(context: PSDL_IOStream): cint64; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetIOSize' {$ENDIF} {$ENDIF}; + +{* + * Seek within an SDL_IOStream data stream. + * + * This function seeks to byte `offset`, relative to `whence`. + * + * `whence` may be any of the following values: + * + * - `SDL_IO_SEEK_SET`: seek from the beginning of data + * - `SDL_IO_SEEK_CUR`: seek relative to current read point + * - `SDL_IO_SEEK_END`: seek relative to the end of data + * + * If this stream can not seek, it will return -1. + * + * \param context a Pointer to an SDL_IOStream structure. + * \param offset an offset in bytes, relative to `whence` location; can be + * negative. + * \param whence any of `SDL_IO_SEEK_SET`, `SDL_IO_SEEK_CUR`, + * `SDL_IO_SEEK_END`. + * \returns the final offset in the data stream after the seek or -1 on + * failure; call SDL_GetError() for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_TellIO + } +function SDL_SeekIO(context: PSDL_IOStream; offset: cint64; whence: TSDL_IOWhence): cint64; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SeekIO' {$ENDIF} {$ENDIF}; + +{* + * Determine the current read/write offset in an SDL_IOStream data stream. + * + * SDL_TellIO is actually a wrapper function that calls the SDL_IOStream's + * `seek` method, with an offset of 0 bytes from `SDL_IO_SEEK_CUR`, to + * simplify application development. + * + * \param context an SDL_IOStream data stream object from which to get the + * current offset. + * \returns the current offset in the stream, or -1 if the information can not + * be determined. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SeekIO + } +function SDL_TellIO(context: PSDL_IOStream): cint64; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TellIO' {$ENDIF} {$ENDIF}; + +{* + * Read from a data source. + * + * This function reads up `size` bytes from the data source to the area + * pointed at by `ptr`. This function may read less bytes than requested. + * + * This function will return zero when the data stream is completely read, and + * SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If zero is returned and + * the stream is not at EOF, SDL_GetIOStatus() will return a different error + * value and SDL_GetError() will offer a human-readable message. + * + * \param context a Pointer to an SDL_IOStream structure. + * \param ptr a Pointer to a buffer to read data into. + * \param size the number of bytes to read from the data source. + * \returns the number of bytes read, or 0 on end of file or other failure; + * call SDL_GetError() for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WriteIO + * \sa SDL_GetIOStatus + } +function SDL_ReadIO(context: PSDL_IOStream; ptr: Pointer; size: csize_t): csize_t; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadIO' {$ENDIF} {$ENDIF}; + +{* + * Write to an SDL_IOStream data stream. + * + * This function writes exactly `size` bytes from the area pointed at by `ptr` + * to the stream. If this fails for any reason, it'll return less than `size` + * to demonstrate how far the write progressed. On success, it returns `size`. + * + * On error, this function still attempts to write as much as possible, so it + * might return a positive value less than the requested write size. + * + * The caller can use SDL_GetIOStatus() to determine if the problem is + * recoverable, such as a non-blocking write that can simply be retried later, + * or a fatal error. + * + * \param context a Pointer to an SDL_IOStream structure. + * \param ptr a Pointer to a buffer containing data to write. + * \param size the number of bytes to write. + * \returns the number of bytes written, which will be less than `size` on + * failure; call SDL_GetError() for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_IOprintf + * \sa SDL_ReadIO + * \sa SDL_SeekIO + * \sa SDL_FlushIO + * \sa SDL_GetIOStatus + } +function SDL_WriteIO(context: PSDL_IOStream; ptr: Pointer; size: csize_t): csize_t; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteIO' {$ENDIF} {$ENDIF}; + +{* + * Print to an SDL_IOStream data stream. + * + * This function does formatted printing to the stream. + * + * \param context a Pointer to an SDL_IOStream structure. + * \param fmt a printf() style format string. + * \param ... additional parameters matching % tokens in the `fmt` string, if + * any. + * \returns the number of bytes written or 0 on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_IOvprintf + * \sa SDL_WriteIO + } +function SDL_IOprintf(context: PSDL_IOStream; fmt: PAnsiChar; Args: array of const): csize_t; cdecl; overload; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IOprintf' {$ENDIF} {$ENDIF}; +function SDL_IOprintf(context: PSDL_IOStream; fmt: PAnsiChar): csize_t; cdecl; overload; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IOprintf' {$ENDIF} {$ENDIF}; + +{* + * Print to an SDL_IOStream data stream. + * + * This function does formatted printing to the stream. + * + * \param context a Pointer to an SDL_IOStream structure. + * \param fmt a printf() style format string. + * \param ap a variable argument list. + * \returns the number of bytes written or 0 on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_IOprintf + * \sa SDL_WriteIO + } +{ #todo : SDL3-for-Pascal: Implement SDL_IOvprintf / va_list } + +{* + * Flush any buffered data in the stream. + * + * This function makes sure that any buffered data is written to the stream. + * Normally this isn't necessary but if the stream is a pipe or socket it + * guarantees that any pending data is sent. + * + * \param context SDL_IOStream structure to flush. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenIO + * \sa SDL_WriteIO + } +function SDL_FlushIO(context: PSDL_IOStream): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_FlushIO' {$ENDIF} {$ENDIF}; + +{* + * Load all the data from an SDL data stream. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in the value reported via + * `datasize`. + * + * The data should be freed with SDL_free(). + * + * \param src the SDL_IOStream to read all available data from. + * \param datasize a Pointer filled in with the number of bytes read, may be + * nil. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. + * \returns the data or nil on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadFile + * \sa SDL_SaveFile_IO + } +function SDL_LoadFile_IO(src: PSDL_IOStream; datasize: pcsize_t; closeio: cbool): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LoadFile_IO' {$ENDIF} {$ENDIF}; + +{* + * Load all the data from a file path. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in the value reported via + * `datasize`. + * + * The data should be freed with SDL_free(). + * + * \param file the path to read all available data from. + * \param datasize if not nil, will store the number of bytes read. + * \returns the data or nil on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadFile_IO + * \sa SDL_SaveFile + } +function SDL_LoadFile(file_: PAnsiChar; datasize: pcsize_t): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LoadFile' {$ENDIF} {$ENDIF}; + +{* + * Save all the data into an SDL data stream. + * + * \param src the SDL_IOStream to write all data to. + * \param data the data to be written. If datasize is 0, may be nil or a + * invalid Pointer. + * \param datasize the number of bytes to be written. + * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even + * in the case of an error. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SaveFile + * \sa SDL_LoadFile_IO + } +function SDL_SaveFile_IO(src: PSDL_IOStream; data: Pointer; datasize: csize_t; closeio: cbool): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SaveFile_IO' {$ENDIF} {$ENDIF}; + +{* + * Save all the data into a file path. + * + * \param file the path to write all available data into. + * \param data the data to be written. If datasize is 0, may be nil or a + * invalid Pointer. + * \param datasize the number of bytes to be written. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SaveFile_IO + * \sa SDL_LoadFile + } +function SDL_SaveFile(file_: PAnsiChar; data: Pointer; datasize: csize_t): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SaveFile' {$ENDIF} {$ENDIF}; + +{* + * \name Read endian functions + * + * Read an item of the specified endianness and return in native format. + } + +{* + * Use this function to read a byte from an SDL_IOStream. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the SDL_IOStream to read from. + * \param value a Pointer filled in with the data read. + * \returns true on success or false on failure or EOF; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_ReadU8(src: PSDL_IOStream; value: pcuint8): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadU8' {$ENDIF} {$ENDIF}; + +{* + * Use this function to read a signed byte from an SDL_IOStream. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the SDL_IOStream to read from. + * \param value a Pointer filled in with the data read. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_ReadS8(src: PSDL_IOStream; value: pcint8): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadS8' {$ENDIF} {$ENDIF}; + +{* + * Use this function to read 16 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a Pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_ReadU16LE(src: PSDL_IOStream; value: pcuint16): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadU16LE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to read 16 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a Pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_ReadS16LE(src: PSDL_IOStream; value: pcint16): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadS16LE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to read 16 bits of big-endian data from an SDL_IOStream + * and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a Pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_ReadU16BE(src: PSDL_IOStream; value: pcuint16): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadU16BE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to read 16 bits of big-endian data from an SDL_IOStream + * and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a Pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_ReadS16BE(src: PSDL_IOStream; value: pcint16): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadS16BE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to read 32 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a Pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_ReadU32LE(src: PSDL_IOStream; value: pcuint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadU32LE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to read 32 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a Pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_ReadS32LE(src: PSDL_IOStream; value: pcint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadS32LE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to read 32 bits of big-endian data from an SDL_IOStream + * and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a Pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_ReadU32BE(src: PSDL_IOStream; value: pcuint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadU32BE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to read 32 bits of big-endian data from an SDL_IOStream + * and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a Pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_ReadS32BE(src: PSDL_IOStream; value: pcint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadS32BE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to read 64 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a Pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_ReadU64LE(src: PSDL_IOStream; value: pcuint64): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadU64LE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to read 64 bits of little-endian data from an + * SDL_IOStream and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a Pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_ReadS64LE(src: PSDL_IOStream; value: pcint64): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadS64LE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to read 64 bits of big-endian data from an SDL_IOStream + * and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a Pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_ReadU64BE(src: PSDL_IOStream; value: pcuint64): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadU64BE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to read 64 bits of big-endian data from an SDL_IOStream + * and return in native format. + * + * SDL byteswaps the data only if necessary, so the data returned will be in + * the native byte order. + * + * This function will return false when the data stream is completely read, + * and SDL_GetIOStatus() will return SDL_IO_STATUS_EOF. If false is returned + * and the stream is not at EOF, SDL_GetIOStatus() will return a different + * error value and SDL_GetError() will offer a human-readable message. + * + * \param src the stream from which to read data. + * \param value a Pointer filled in with the data read. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_ReadS64BE(src: PSDL_IOStream; value: pcint64): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadS64BE' {$ENDIF} {$ENDIF}; + +{ Read endian functions } + +{* + * \name Write endian functions + * + * Write an item of native format to the specified endianness. + } + +{* + * Use this function to write a byte to an SDL_IOStream. + * + * \param dst the SDL_IOStream to write to. + * \param value the byte value to write. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_WriteU8(dst: PSDL_IOStream; value: cuint8): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteU8' {$ENDIF} {$ENDIF}; + +{* + * Use this function to write a signed byte to an SDL_IOStream. + * + * \param dst the SDL_IOStream to write to. + * \param value the byte value to write. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_WriteS8(dst: PSDL_IOStream; value: cint8): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteS8' {$ENDIF} {$ENDIF}; + +{* + * Use this function to write 16 bits in native format to an SDL_IOStream as + * little-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in little-endian + * format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_WriteU16LE(dst: PSDL_IOStream; value: cuint16): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteU16LE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to write 16 bits in native format to an SDL_IOStream as + * little-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in little-endian + * format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_WriteS16LE(dst: PSDL_IOStream; value: cint16): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteS16LE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to write 16 bits in native format to an SDL_IOStream as + * big-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in big-endian format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_WriteU16BE(dst: PSDL_IOStream; value: cuint16): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteU16BE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to write 16 bits in native format to an SDL_IOStream as + * big-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in big-endian format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_WriteS16BE(dst: PSDL_IOStream; value: cint16): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteS16BE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to write 32 bits in native format to an SDL_IOStream as + * little-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in little-endian + * format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_WriteU32LE(dst: PSDL_IOStream; value: cuint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteU32LE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to write 32 bits in native format to an SDL_IOStream as + * little-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in little-endian + * format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_WriteS32LE(dst: PSDL_IOStream; value: cint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteS32LE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to write 32 bits in native format to an SDL_IOStream as + * big-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in big-endian format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_WriteU32BE(dst: PSDL_IOStream; value: cuint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteU32BE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to write 32 bits in native format to an SDL_IOStream as + * big-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in big-endian format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_WriteS32BE(dst: PSDL_IOStream; value: cint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteS32BE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to write 64 bits in native format to an SDL_IOStream as + * little-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in little-endian + * format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_WriteU64LE(dst: PSDL_IOStream; value: cuint64): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteU64LE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to write 64 bits in native format to an SDL_IOStream as + * little-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in little-endian + * format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_WriteS64LE(dst: PSDL_IOStream; value: cint64): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteS64LE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to write 64 bits in native format to an SDL_IOStream as + * big-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in big-endian format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_WriteU64BE(dst: PSDL_IOStream; value: cuint64): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteU64BE' {$ENDIF} {$ENDIF}; + +{* + * Use this function to write 64 bits in native format to an SDL_IOStream as + * big-endian data. + * + * SDL byteswaps the data only if necessary, so the application always + * specifies native format, and the data written will be in big-endian format. + * + * \param dst the stream to which data will be written. + * \param value the data to be written, in native format. + * \returns true on successful write or false on failure; call SDL_GetError() + * for more information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_WriteS64BE(dst: PSDL_IOStream; value: cint64): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteS64BE' {$ENDIF} {$ENDIF}; + From 1fc44266cccac1acbc3260ff65bd232349c07cd1 Mon Sep 17 00:00:00 2001 From: Matthias Date: Thu, 6 Feb 2025 10:31:39 +0100 Subject: [PATCH 07/18] Add SDL_asyncio.inc --- units/SDL3.pas | 1 + units/SDL_asyncio.inc | 534 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 535 insertions(+) create mode 100644 units/SDL_asyncio.inc diff --git a/units/SDL3.pas b/units/SDL3.pas index 72906f6..80739b7 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -86,6 +86,7 @@ interface {$I SDL_pixels.inc} // 3.1.6-prev {$I SDL_blendmode.inc} // 3.1.6-prev {$I SDL_iostream.inc} // 3.2.0 +{$I SDL_asyncio.inc} // 3.2.0 {$I SDL_surface.inc} // 3.1.6-prev {$I SDL_video.inc} // 3.1.6-prev {$I SDL_timer.inc} // 3.1.6-prev diff --git a/units/SDL_asyncio.inc b/units/SDL_asyncio.inc new file mode 100644 index 0000000..2f11dd6 --- /dev/null +++ b/units/SDL_asyncio.inc @@ -0,0 +1,534 @@ +{ + This file is part of: + + SDL3 for Pascal + (https://github.com/PascalGameDevelopment/SDL3-for-Pascal) + SPDX-License-Identifier: Zlib +} + +{* + * # CategoryAsyncIO + * + * SDL offers a way to perform I/O asynchronously. This allows an app to read + * or write files without waiting for data to actually transfer; the functions + * that request I/O never block while the request is fulfilled. + * + * Instead, the data moves in the background and the app can check for results + * at their leisure. + * + * This is more complicated than just reading and writing files in a + * synchronous way, but it can allow for more efficiency, and never having + * framerate drops as the hard drive catches up, etc. + * + * The general usage pattern for async I/O is: + * + * - Create one or more SDL_AsyncIOQueue objects. + * - Open files with SDL_AsyncIOFromFile. + * - Start I/O tasks to the files with SDL_ReadAsyncIO or SDL_WriteAsyncIO, + * putting those tasks into one of the queues. + * - Later on, use SDL_GetAsyncIOResult on a queue to see if any task is + * finished without blocking. Tasks might finish in any order with success + * or failure. + * - When all your tasks are done, close the file with SDL_CloseAsyncIO. This + * also generates a task, since it might flush data to disk! + * + * This all works, without blocking, in a single thread, but one can also wait + * on a queue in a background thread, sleeping until new results have arrived: + * + * - Call SDL_WaitAsyncIOResult from one or more threads to efficiently block + * until new tasks complete. + * - When shutting down, call SDL_SignalAsyncIOQueue to unblock any sleeping + * threads despite there being no new tasks completed. + * + * And, of course, to match the synchronous SDL_LoadFile, we offer + * SDL_LoadFileAsync as a convenience function. This will handle allocating a + * buffer, slurping in the file data, and null-terminating it; you still check + * for results later. + * + * Behind the scenes, SDL will use newer, efficient APIs on platforms that + * support them: Linux's io_uring and Windows 11's IoRing, for example. If + * those technologies aren't available, SDL will offload the work to a thread + * pool that will manage otherwise-synchronous loads without blocking the app. + * + * ## Best Practices + * + * Simple non-blocking I/O--for an app that just wants to pick up data + * whenever it's ready without losing framerate waiting on disks to spin--can + * use whatever pattern works well for the program. In this case, simply call + * SDL_ReadAsyncIO, or maybe SDL_LoadFileAsync, as needed. Once a frame, call + * SDL_GetAsyncIOResult to check for any completed tasks and deal with the + * data as it arrives. + * + * If two separate pieces of the same program need their own I/O, it is legal + * for each to create their own queue. This will prevent either piece from + * accidentally consuming the other's completed tasks. Each queue does require + * some amount of resources, but it is not an overwhelming cost. Do not make a + * queue for each task, however. It is better to put many tasks into a single + * queue. They will be reported in order of completion, not in the order they + * were submitted, so it doesn't generally matter what order tasks are + * started. + * + * One async I/O queue can be shared by multiple threads, or one thread can + * have more than one queue, but the most efficient way--if ruthless + * efficiency is the goal--is to have one queue per thread, with multiple + * threads working in parallel, and attempt to keep each queue loaded with + * tasks that are both started by and consumed by the same thread. On modern + * platforms that can use newer interfaces, this can keep data flowing as + * efficiently as possible all the way from storage hardware to the app, with + * no contention between threads for access to the same queue. + * + * Written data is not guaranteed to make it to physical media by the time a + * closing task is completed, unless SDL_CloseAsyncIO is called with its + * `flush` parameter set to true, which is to say that a successful result + * here can still result in lost data during an unfortunately-timed power + * outage if not flushed. However, flushing will take longer and may be + * unnecessary, depending on the app's needs. + } + +{* + * The asynchronous I/O operation structure. + * + * This operates as an opaque handle. One can then request read or write + * operations on it. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_AsyncIOFromFile + } +type + PPSDL_AsyncIO = ^PSDL_AsyncIO; + PSDL_AsyncIO = type Pointer; + +{* + * Types of asynchronous I/O tasks. + * + * \since This enum is available since SDL 3.2.0. + } +type + PPSDL_AsyncIOTaskType = ^PSDL_AsyncIOTaskType; + PSDL_AsyncIOTaskType = ^TSDL_AsyncIOTaskType; + TSDL_AsyncIOTaskType = type Integer; +const + SDL_ASYNCIO_TASK_READ = TSDL_AsyncIOTaskType(0); {*< A read operation. } + SDL_ASYNCIO_TASK_WRITE = TSDL_AsyncIOTaskType(1); {*< A write operation. } + SDL_ASYNCIO_TASK_CLOSE = TSDL_AsyncIOTaskType(2); {*< A close operation. } + +{* + * Possible outcomes of an asynchronous I/O task. + * + * \since This enum is available since SDL 3.2.0. + } +type + PPSDL_AsyncIOResult = ^PSDL_AsyncIOResult; + PSDL_AsyncIOResult = ^TSDL_AsyncIOResult; + TSDL_AsyncIOResult = type Integer; +const + SDL_ASYNCIO_COMPLETE = TSDL_AsyncIOResult(0); {*< request was completed without error } + SDL_ASYNCIO_FAILURE = TSDL_AsyncIOResult(1); {*< request failed for some reason; check SDL_GetError()! } + SDL_ASYNCIO_CANCELED = TSDL_AsyncIOResult(2); {*< request was canceled before completing. } + +{* + * Information about a completed asynchronous I/O request. + * + * \since This struct is available since SDL 3.2.0. + } +type + PPSDL_AsyncIOOutcome = ^PSDL_AsyncIOOutcome; + PSDL_AsyncIOOutcome = ^TSDL_AsyncIOOutcome; + TSDL_AsyncIOOutcome = record + asyncio: PSDL_AsyncIO; {*< what generated this task. This Pointer will be invalid if it was closed! } + type_: TSDL_AsyncIOTaskType; {*< What sort of task was this? Read, write, etc? } + result: TSDL_AsyncIOResult; {*< the result of the work (success, failure, cancellation). } + buffer: Pointer; {*< buffer where data was read/written. } + offset: cuint64; {*< offset in the SDL_AsyncIO where data was read/written. } + bytes_requested: cuint64; {*< number of bytes the task was to read/write. } + bytes_transferred: cuint64; {*< actual number of bytes that were read/written. } + userdata: Pointer; {*< Pointer provided by the app when starting the task } + end; + +{* + * A queue of completed asynchronous I/O tasks. + * + * When starting an asynchronous operation, you specify a queue for the new + * task. A queue can be asked later if any tasks in it have completed, + * allowing an app to manage multiple pending tasks in one place, in whatever + * order they complete. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_CreateAsyncIOQueue + * \sa SDL_ReadAsyncIO + * \sa SDL_WriteAsyncIO + * \sa SDL_GetAsyncIOResult + * \sa SDL_WaitAsyncIOResult + } +type + PPSDL_AsyncIOQueue = ^PSDL_AsyncIOQueue; + PSDL_AsyncIOQueue = type Pointer; + +{* + * Use this function to create a new SDL_AsyncIO object for reading from + * and/or writing to a named file. + * + * The `mode` string understands the following values: + * + * - "r": Open a file for reading only. It must exist. + * - "w": Open a file for writing only. It will create missing files or + * truncate existing ones. + * - "r+": Open a file for update both reading and writing. The file must + * exist. + * - "w+": Create an empty file for both reading and writing. If a file with + * the same name already exists its content is erased and the file is + * treated as a new empty file. + * + * There is no "b" mode, as there is only "binary" style I/O, and no "a" mode + * for appending, since you specify the position when starting a task. + * + * This function supports Unicode filenames, but they must be encoded in UTF-8 + * format, regardless of the underlying operating system. + * + * This call is _not_ asynchronous; it will open the file before returning, + * under the assumption that doing so is generally a fast operation. Future + * reads and writes to the opened file will be async, however. + * + * \param file a UTF-8 string representing the filename to open. + * \param mode an ASCII string representing the mode to be used for opening + * the file. + * \returns a Pointer to the SDL_AsyncIO structure that is created or nil on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseAsyncIO + * \sa SDL_ReadAsyncIO + * \sa SDL_WriteAsyncIO + } +function SDL_AsyncIOFromFile(file_: PAnsiChar; mode: PAnsiChar): PSDL_AsyncIO; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AsyncIOFromFile' {$ENDIF} {$ENDIF}; + +{* + * Use this function to get the size of the data stream in an SDL_AsyncIO. + * + * This call is _not_ asynchronous; it assumes that obtaining this info is a + * non-blocking operation in most reasonable cases. + * + * \param asyncio the SDL_AsyncIO to get the size of the data stream from. + * \returns the size of the data stream in the SDL_IOStream on success or a + * negative error code on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetAsyncIOSize(asyncio: PSDL_AsyncIO): cint64; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetAsyncIOSize' {$ENDIF} {$ENDIF}; + +{* + * Start an async read. + * + * This function reads up to `size` bytes from `offset` position in the data + * source to the area pointed at by `ptr`. This function may read less bytes + * than requested. + * + * This function returns as quickly as possible; it does not wait for the read + * to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * `ptr` must remain available until the work is done, and may be accessed by + * the system at any time until then. Do not allocate it on the stack, as this + * might take longer than the life of the calling function to complete! + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a Pointer to an SDL_AsyncIO structure. + * \param ptr a Pointer to a buffer to read data into. + * \param offset the position to start reading in the data source. + * \param size the number of bytes to read from the data source. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined Pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WriteAsyncIO + * \sa SDL_CreateAsyncIOQueue + } +function SDL_ReadAsyncIO(asyncio: PSDL_AsyncIO; ptr: Pointer; offset: cuint64; size: cuint64; queue: PSDL_AsyncIOQueue; userdata: Pointer): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadAsyncIO' {$ENDIF} {$ENDIF}; + +{* + * Start an async write. + * + * This function writes `size` bytes from `offset` position in the data source + * to the area pointed at by `ptr`. + * + * This function returns as quickly as possible; it does not wait for the + * write to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * `ptr` must remain available until the work is done, and may be accessed by + * the system at any time until then. Do not allocate it on the stack, as this + * might take longer than the life of the calling function to complete! + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a Pointer to an SDL_AsyncIO structure. + * \param ptr a Pointer to a buffer to write data from. + * \param offset the position to start writing to the data source. + * \param size the number of bytes to write to the data source. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined Pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ReadAsyncIO + * \sa SDL_CreateAsyncIOQueue + } +function SDL_WriteAsyncIO(asyncio: PSDL_AsyncIO; ptr: Pointer; offset: cuint64; size: cuint64; queue: PSDL_AsyncIOQueue; userdata: Pointer): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteAsyncIO' {$ENDIF} {$ENDIF}; + +{* + * Close and free any allocated resources for an async I/O object. + * + * Closing a file is _also_ an asynchronous task! If a write failure were to + * happen during the closing process, for example, the task results will + * report it as usual. + * + * Closing a file that has been written to does not guarantee the data has + * made it to physical media; it may remain in the operating system's file + * cache, for later writing to disk. This means that a successfully-closed + * file can be lost if the system crashes or loses power in this small window. + * To prevent this, call this function with the `flush` parameter set to true. + * This will make the operation take longer, and perhaps increase system load + * in general, but a successful result guarantees that the data has made it to + * physical storage. Don't use this for temporary files, caches, and + * unimportant data, and definitely use it for crucial irreplaceable files, + * like game saves. + * + * This function guarantees that the close will happen after any other pending + * tasks to `asyncio`, so it's safe to open a file, start several operations, + * close the file immediately, then check for all results later. This function + * will not block until the tasks have completed. + * + * Once this function returns true, `asyncio` is no longer valid, regardless + * of any future outcomes. Any completed tasks might still contain this + * Pointer in their SDL_AsyncIOOutcome data, in case the app was using this + * value to track information, but it should not be used again. + * + * If this function returns false, the close wasn't started at all, and it's + * safe to attempt to close again later. + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param asyncio a Pointer to an SDL_AsyncIO structure to close. + * \param flush true if data should sync to disk before the task completes. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined Pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread, but two + * threads should not attempt to close the same object. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_CloseAsyncIO(asyncio: PSDL_AsyncIO; flush: cbool; queue: PSDL_AsyncIOQueue; userdata: Pointer): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CloseAsyncIO' {$ENDIF} {$ENDIF}; + +{* + * Create a task queue for tracking multiple I/O operations. + * + * Async I/O operations are assigned to a queue when started. The queue can be + * checked for completed tasks thereafter. + * + * \returns a new task queue object or nil if there was an error; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DestroyAsyncIOQueue + * \sa SDL_GetAsyncIOResult + * \sa SDL_WaitAsyncIOResult + } +function SDL_CreateAsyncIOQueue: PSDL_AsyncIOQueue; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateAsyncIOQueue' {$ENDIF} {$ENDIF}; + +{* + * Destroy a previously-created async I/O task queue. + * + * If there are still tasks pending for this queue, this call will block until + * those tasks are finished. All those tasks will be deallocated. Their + * results will be lost to the app. + * + * Any pending reads from SDL_LoadFileAsync() that are still in this queue + * will have their buffers deallocated by this function, to prevent a memory + * leak. + * + * Once this function is called, the queue is no longer valid and should not + * be used, including by other threads that might access it while destruction + * is blocking on pending tasks. + * + * Do not destroy a queue that still has threads waiting on it through + * SDL_WaitAsyncIOResult(). You can call SDL_SignalAsyncIOQueue() first to + * unblock those threads, and take measures (such as SDL_WaitThread()) to make + * sure they have finished their wait and won't wait on the queue again. + * + * \param queue the task queue to destroy. + * + * \threadsafety It is safe to call this function from any thread, so long as + * no other thread is waiting on the queue with + * SDL_WaitAsyncIOResult. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_DestroyAsyncIOQueue(queue: PSDL_AsyncIOQueue); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DestroyAsyncIOQueue' {$ENDIF} {$ENDIF}; + +{* + * Query an async I/O task queue for completed tasks. + * + * If a task assigned to this queue has finished, this will return true and + * fill in `outcome` with the details of the task. If no task in the queue has + * finished, this function will return false. This function does not block. + * + * If a task has completed, this function will free its resources and the task + * Pointer will no longer be valid. The task will be removed from the queue. + * + * It is safe for multiple threads to call this function on the same queue at + * once; a completed task will only go to one of the threads. + * + * \param queue the async I/O task queue to query. + * \param outcome details of a finished task will be written here. May not be + * nil. + * \returns true if a task has completed, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAsyncIOResult + } +function SDL_GetAsyncIOResult(queue: PSDL_AsyncIOQueue; outcome: PSDL_AsyncIOOutcome): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetAsyncIOResult' {$ENDIF} {$ENDIF}; + +{* + * Block until an async I/O task queue has a completed task. + * + * This function puts the calling thread to sleep until there a task assigned + * to the queue that has finished. + * + * If a task assigned to the queue has finished, this will return true and + * fill in `outcome` with the details of the task. If no task in the queue has + * finished, this function will return false. + * + * If a task has completed, this function will free its resources and the task + * Pointer will no longer be valid. The task will be removed from the queue. + * + * It is safe for multiple threads to call this function on the same queue at + * once; a completed task will only go to one of the threads. + * + * Note that by the nature of various platforms, more than one waiting thread + * may wake to handle a single task, but only one will obtain it, so + * `timeoutMS` is a _maximum_ wait time, and this function may return false + * sooner. + * + * This function may return false if there was a system error, the OS + * inadvertently awoke multiple threads, or if SDL_SignalAsyncIOQueue() was + * called to wake up all waiting threads without a finished task. + * + * A timeout can be used to specify a maximum wait time, but rather than + * polling, it is possible to have a timeout of -1 to wait forever, and use + * SDL_SignalAsyncIOQueue() to wake up the waiting threads later. + * + * \param queue the async I/O task queue to wait on. + * \param outcome details of a finished task will be written here. May not be + * nil. + * \param timeoutMS the maximum time to wait, in milliseconds, or -1 to wait + * indefinitely. + * \returns true if task has completed, false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SignalAsyncIOQueue + } +function SDL_WaitAsyncIOResult(queue: PSDL_AsyncIOQueue; outcome: PSDL_AsyncIOOutcome; timeoutMS: cint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WaitAsyncIOResult' {$ENDIF} {$ENDIF}; + +{* + * Wake up any threads that are blocking in SDL_WaitAsyncIOResult(). + * + * This will unblock any threads that are sleeping in a call to + * SDL_WaitAsyncIOResult for the specified queue, and cause them to return + * from that function. + * + * This can be useful when destroying a queue to make sure nothing is touching + * it indefinitely. In this case, once this call completes, the caller should + * take measures to make sure any previously-blocked threads have returned + * from their wait and will not touch the queue again (perhaps by setting a + * flag to tell the threads to terminate and then using SDL_WaitThread() to + * make sure they've done so). + * + * \param queue the async I/O task queue to signal. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_WaitAsyncIOResult + } +procedure SDL_SignalAsyncIOQueue(queue: PSDL_AsyncIOQueue); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SignalAsyncIOQueue' {$ENDIF} {$ENDIF}; + +{* + * Load all the data from a file path, asynchronously. + * + * This function returns as quickly as possible; it does not wait for the read + * to complete. On a successful return, this work will continue in the + * background. If the work begins, even failure is asynchronous: a failing + * return value from this function only means the work couldn't start at all. + * + * The data is allocated with a zero byte at the end (null terminated) for + * convenience. This extra byte is not included in SDL_AsyncIOOutcome's + * bytes_transferred value. + * + * This function will allocate the buffer to contain the file. It must be + * deallocated by calling SDL_free() on SDL_AsyncIOOutcome's buffer field + * after completion. + * + * An SDL_AsyncIOQueue must be specified. The newly-created task will be added + * to it when it completes its work. + * + * \param file the path to read all available data from. + * \param queue a queue to add the new SDL_AsyncIO to. + * \param userdata an app-defined Pointer that will be provided with the task + * results. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadFile_IO + } +function SDL_LoadFileAsync(file_: PAnsiChar; queue: PSDL_AsyncIOQueue; userdata: Pointer): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LoadFileAsync' {$ENDIF} {$ENDIF}; + From ee1c0dfe37e4e4581c3f7622165586c1e2659c75 Mon Sep 17 00:00:00 2001 From: Matthias Date: Thu, 6 Feb 2025 10:45:41 +0100 Subject: [PATCH 08/18] Add SDL_hints.inc --- units/SDL3.pas | 1 + units/SDL_hints.inc | 4425 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 4426 insertions(+) create mode 100644 units/SDL_hints.inc diff --git a/units/SDL3.pas b/units/SDL3.pas index 80739b7..f214d75 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -80,6 +80,7 @@ interface {$I SDL_version.inc} // 3.1.6-prev {$I SDL_revision.inc} // 3.1.6-prev {$I SDL_guid.inc} // 3.1.6-prev +{$I SDL_hints.inc} // 3.2.0 {$I SDL_stdinc.inc} // 3.1.6-prev (unfinished) {$I SDL_rect.inc} // 3.1.6-prev {$I SDL_properties.inc} // 3.1.6-prev diff --git a/units/SDL_hints.inc b/units/SDL_hints.inc new file mode 100644 index 0000000..69eb69a --- /dev/null +++ b/units/SDL_hints.inc @@ -0,0 +1,4425 @@ +{ + This file is part of: + + SDL3 for Pascal + (https://github.com/PascalGameDevelopment/SDL3-for-Pascal) + SPDX-License-Identifier: Zlib +} + +{* + * # CategoryHints + * + * This file contains functions to set and get configuration hints, as well as + * listing each of them alphabetically. + * + * The convention for naming hints is SDL_HINT_X, where "SDL_X" is the + * environment variable that can be used to override the default. + * + * In general these hints are just that - they may or may not be supported or + * applicable on any given platform, but they provide a way for an application + * or user to give the library a hint as to how they would like the library to + * work. + } + +{* + * Specify the behavior of Alt+Tab while the keyboard is grabbed. + * + * By default, SDL emulates Alt+Tab functionality while the keyboard is + * grabbed and your window is full-screen. This prevents the user from getting + * stuck in your application if you've enabled keyboard grab. + * + * The variable can be set to the following values: + * + * - "0": SDL will not handle Alt+Tab. Your application is responsible for + * handling Alt+Tab while the keyboard is grabbed. + * - "1": SDL will minimize your window when Alt+Tab is pressed (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } +const + SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED = 'SDL_ALLOW_ALT_TAB_WHILE_GRABBED'; + +{* + * A variable to control whether the SDL activity is allowed to be re-created. + * + * If this hint is true, the activity can be recreated on demand by the OS, + * and Java static data and C++ static data remain with their current values. + * If this hint is false, then SDL will call exit() when you return from your + * main function and the application will be terminated and then started fresh + * each time. + * + * The variable can be set to the following values: + * + * - "0": The application starts fresh at each launch. (default) + * - "1": The application activity can be recreated by the OS. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_ANDROID_ALLOW_RECREATE_ACTIVITY = 'SDL_ANDROID_ALLOW_RECREATE_ACTIVITY'; + +{* + * A variable to control whether the event loop will block itself when the app + * is paused. + * + * The variable can be set to the following values: + * + * - "0": Non blocking. + * - "1": Blocking. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_ANDROID_BLOCK_ON_PAUSE = 'SDL_ANDROID_BLOCK_ON_PAUSE'; + +{* + * A variable to control whether low latency audio should be enabled. + * + * Some devices have poor quality output when this is enabled, but this is + * usually an improvement in audio latency. + * + * The variable can be set to the following values: + * + * - "0": Low latency audio is not enabled. + * - "1": Low latency audio is enabled. (default) + * + * This hint should be set before SDL audio is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_ANDROID_LOW_LATENCY_AUDIO = 'SDL_ANDROID_LOW_LATENCY_AUDIO'; + +{* + * A variable to control whether we trap the Android back button to handle it + * manually. + * + * This is necessary for the right mouse button to work on some Android + * devices, or to be able to trap the back button for use in your code + * reliably. If this hint is true, the back button will show up as an + * SDL_EVENT_KEY_DOWN / SDL_EVENT_KEY_UP pair with a keycode of + * SDL_SCANCODE_AC_BACK. + * + * The variable can be set to the following values: + * + * - "0": Back button will be handled as usual for system. (default) + * - "1": Back button will be trapped, allowing you to handle the key press + * manually. (This will also let right mouse click work on systems where the + * right mouse button functions as back.) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_ANDROID_TRAP_BACK_BUTTON = 'SDL_ANDROID_TRAP_BACK_BUTTON'; + +{* + * A variable setting the app ID string. + * + * This string is used by desktop compositors to identify and group windows + * together, as well as match applications with associated desktop settings + * and icons. + * + * This will override SDL_PROP_APP_METADATA_IDENTIFIER_STRING, if set by the + * application. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_APP_ID = 'SDL_APP_ID'; + +{* + * A variable setting the application name. + * + * This hint lets you specify the application name sent to the OS when + * required. For example, this will often appear in volume control applets for + * audio streams, and in lists of applications which are inhibiting the + * screensaver. You should use a string that describes your program ("My Game + * 2: The Revenge") + * + * This will override SDL_PROP_APP_METADATA_NAME_STRING, if set by the + * application. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_APP_NAME = 'SDL_APP_NAME'; + +{* + * A variable controlling whether controllers used with the Apple TV generate + * UI events. + * + * When UI events are generated by controller input, the app will be + * backgrounded when the Apple TV remote's menu button is pressed, and when + * the pause or B buttons on gamepads are pressed. + * + * More information about properly making use of controllers for the Apple TV + * can be found here: + * https://developer.apple.com/tvos/human-interface-guidelines/remote-and-controllers/ + * + * The variable can be set to the following values: + * + * - "0": Controller input does not generate UI events. (default) + * - "1": Controller input generates UI events. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_APPLE_TV_CONTROLLER_UI_EVENTS = 'SDL_APPLE_TV_CONTROLLER_UI_EVENTS'; + +{* + * A variable controlling whether the Apple TV remote's joystick axes will + * automatically match the rotation of the remote. + * + * The variable can be set to the following values: + * + * - "0": Remote orientation does not affect joystick axes. (default) + * - "1": Joystick axes are based on the orientation of the remote. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_APPLE_TV_REMOTE_ALLOW_ROTATION = 'SDL_APPLE_TV_REMOTE_ALLOW_ROTATION'; + +{* + * Specify the default ALSA audio device name. + * + * This variable is a specific audio device to open when the "default" audio + * device is used. + * + * This hint will be ignored when opening the default playback device if + * SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE is set, or when opening the + * default recording device if SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE is + * set. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE + } + SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE = 'SDL_AUDIO_ALSA_DEFAULT_DEVICE'; + +{* + * Specify the default ALSA audio playback device name. + * + * This variable is a specific audio device to open for playback, when the + * "default" audio device is used. + * + * If this hint isn't set, SDL will check SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + * before choosing a reasonable default. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + } + SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE = 'SDL_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE'; + +{* + * Specify the default ALSA audio recording device name. + * + * This variable is a specific audio device to open for recording, when the + * "default" audio device is used. + * + * If this hint isn't set, SDL will check SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + * before choosing a reasonable default. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_PLAYBACK_DEVICE + * \sa SDL_HINT_AUDIO_ALSA_DEFAULT_DEVICE + } + SDL_HINT_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE = 'SDL_AUDIO_ALSA_DEFAULT_RECORDING_DEVICE'; + +{* + * A variable controlling the audio category on iOS and macOS. + * + * The variable can be set to the following values: + * + * - "ambient": Use the AVAudioSessionCategoryAmbient audio category, will be + * muted by the phone mute switch (default) + * - "playback": Use the AVAudioSessionCategoryPlayback category. + * + * For more information, see Apple's documentation: + * https://developer.apple.com/library/content/documentation/Audio/Conceptual/AudioSessionProgrammingGuide/AudioSessionCategoriesandModes/AudioSessionCategoriesandModes.html + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_AUDIO_CATEGORY = 'SDL_AUDIO_CATEGORY'; + +{* + * A variable controlling the default audio channel count. + * + * If the application doesn't specify the audio channel count when opening the + * device, this hint can be used to specify a default channel count that will + * be used. This defaults to "1" for recording and "2" for playback devices. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_AUDIO_CHANNELS = 'SDL_AUDIO_CHANNELS'; + +{* + * Specify an application icon name for an audio device. + * + * Some audio backends (such as Pulseaudio and Pipewire) allow you to set an + * XDG icon name for your application. Among other things, this icon might + * show up in a system control panel that lets the user adjust the volume on + * specific audio streams instead of using one giant master volume slider. + * Note that this is unrelated to the icon used by the windowing system, which + * may be set with SDL_SetWindowIcon (or via desktop file on Wayland). + * + * Setting this to "" or leaving it unset will have SDL use a reasonable + * default, "applications-games", which is likely to be installed. See + * https://specifications.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html + * and + * https://specifications.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html + * for the relevant XDG icon specs. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_AUDIO_DEVICE_APP_ICON_NAME = 'SDL_AUDIO_DEVICE_APP_ICON_NAME'; + +{* + * A variable controlling device buffer size. + * + * This hint is an integer > 0, that represents the size of the device's + * buffer in sample frames (stereo audio data in 16-bit format is 4 bytes per + * sample frame, for example). + * + * SDL3 generally decides this value on behalf of the app, but if for some + * reason the app needs to dictate this (because they want either lower + * latency or higher throughput AND ARE WILLING TO DEAL WITH what that might + * require of the app), they can specify it. + * + * SDL will try to accommodate this value, but there is no promise you'll get + * the buffer size requested. Many platforms won't honor this request at all, + * or might adjust it. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_AUDIO_DEVICE_SAMPLE_FRAMES = 'SDL_AUDIO_DEVICE_SAMPLE_FRAMES'; + +{* + * Specify an audio stream name for an audio device. + * + * Some audio backends (such as PulseAudio) allow you to describe your audio + * stream. Among other things, this description might show up in a system + * control panel that lets the user adjust the volume on specific audio + * streams instead of using one giant master volume slider. + * + * This hints lets you transmit that information to the OS. The contents of + * this hint are used while opening an audio device. You should use a string + * that describes your what your program is playing ("audio stream" is + * probably sufficient in many cases, but this could be useful for something + * like "team chat" if you have a headset playing VoIP audio separately). + * + * Setting this to "" or leaving it unset will have SDL use a reasonable + * default: "audio stream" or something similar. + * + * Note that while this talks about audio streams, this is an OS-level + * concept, so it applies to a physical audio device in this case, and not an + * SDL_AudioStream, nor an SDL logical audio device. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_AUDIO_DEVICE_STREAM_NAME = 'SDL_AUDIO_DEVICE_STREAM_NAME'; + +{* + * Specify an application role for an audio device. + * + * Some audio backends (such as Pipewire) allow you to describe the role of + * your audio stream. Among other things, this description might show up in a + * system control panel or software for displaying and manipulating media + * playback/recording graphs. + * + * This hints lets you transmit that information to the OS. The contents of + * this hint are used while opening an audio device. You should use a string + * that describes your what your program is playing (Game, Music, Movie, + * etc...). + * + * Setting this to "" or leaving it unset will have SDL use a reasonable + * default: "Game" or something similar. + * + * Note that while this talks about audio streams, this is an OS-level + * concept, so it applies to a physical audio device in this case, and not an + * SDL_AudioStream, nor an SDL logical audio device. + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_AUDIO_DEVICE_STREAM_ROLE = 'SDL_AUDIO_DEVICE_STREAM_ROLE'; + +{* + * Specify the input file when recording audio using the disk audio driver. + * + * This defaults to "sdlaudio-in.raw" + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_AUDIO_DISK_INPUT_FILE = 'SDL_AUDIO_DISK_INPUT_FILE'; + +{* + * Specify the output file when playing audio using the disk audio driver. + * + * This defaults to "sdlaudio.raw" + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_AUDIO_DISK_OUTPUT_FILE = 'SDL_AUDIO_DISK_OUTPUT_FILE'; + +{* + * A variable controlling the audio rate when using the disk audio driver. + * + * The disk audio driver normally simulates real-time for the audio rate that + * was specified, but you can use this variable to adjust this rate higher or + * lower down to 0. The default value is "1.0". + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_AUDIO_DISK_TIMESCALE = 'SDL_AUDIO_DISK_TIMESCALE'; + +{* + * A variable that specifies an audio backend to use. + * + * By default, SDL will try all available audio backends in a reasonable order + * until it finds one that can work, but this hint allows the app or user to + * force a specific driver, such as "pipewire" if, say, you are on PulseAudio + * but want to try talking to the lower level instead. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_AUDIO_DRIVER = 'SDL_AUDIO_DRIVER'; + +{* + * A variable controlling the audio rate when using the dummy audio driver. + * + * The dummy audio driver normally simulates real-time for the audio rate that + * was specified, but you can use this variable to adjust this rate higher or + * lower down to 0. The default value is "1.0". + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_AUDIO_DUMMY_TIMESCALE = 'SDL_AUDIO_DUMMY_TIMESCALE'; + +{* + * A variable controlling the default audio format. + * + * If the application doesn't specify the audio format when opening the + * device, this hint can be used to specify a default format that will be + * used. + * + * The variable can be set to the following values: + * + * - "U8": Unsigned 8-bit audio + * - "S8": Signed 8-bit audio + * - "S16LE": Signed 16-bit little-endian audio + * - "S16BE": Signed 16-bit big-endian audio + * - "S16": Signed 16-bit native-endian audio (default) + * - "S32LE": Signed 32-bit little-endian audio + * - "S32BE": Signed 32-bit big-endian audio + * - "S32": Signed 32-bit native-endian audio + * - "F32LE": Floating point little-endian audio + * - "F32BE": Floating point big-endian audio + * - "F32": Floating point native-endian audio + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_AUDIO_FORMAT = 'SDL_AUDIO_FORMAT'; + +{* + * A variable controlling the default audio frequency. + * + * If the application doesn't specify the audio frequency when opening the + * device, this hint can be used to specify a default frequency that will be + * used. This defaults to "44100". + * + * This hint should be set before an audio device is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_AUDIO_FREQUENCY = 'SDL_AUDIO_FREQUENCY'; + +{* + * A variable that causes SDL to not ignore audio "monitors". + * + * This is currently only used by the PulseAudio driver. + * + * By default, SDL ignores audio devices that aren't associated with physical + * hardware. Changing this hint to "1" will expose anything SDL sees that + * appears to be an audio source or sink. This will add "devices" to the list + * that the user probably doesn't want or need, but it can be useful in + * scenarios where you want to hook up SDL to some sort of virtual device, + * etc. + * + * The variable can be set to the following values: + * + * - "0": Audio monitor devices will be ignored. (default) + * - "1": Audio monitor devices will show up in the device list. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_AUDIO_INCLUDE_MONITORS = 'SDL_AUDIO_INCLUDE_MONITORS'; + +{* + * A variable controlling whether SDL updates joystick state when getting + * input events. + * + * The variable can be set to the following values: + * + * - "0": You'll call SDL_UpdateJoysticks() manually. + * - "1": SDL will automatically call SDL_UpdateJoysticks(). (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_AUTO_UPDATE_JOYSTICKS = 'SDL_AUTO_UPDATE_JOYSTICKS'; + +{* + * A variable controlling whether SDL updates sensor state when getting input + * events. + * + * The variable can be set to the following values: + * + * - "0": You'll call SDL_UpdateSensors() manually. + * - "1": SDL will automatically call SDL_UpdateSensors(). (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_AUTO_UPDATE_SENSORS = 'SDL_AUTO_UPDATE_SENSORS'; + +{* + * Prevent SDL from using version 4 of the bitmap header when saving BMPs. + * + * The bitmap header version 4 is required for proper alpha channel support + * and SDL will use it when required. Should this not be desired, this hint + * can force the use of the 40 byte header version which is supported + * everywhere. + * + * The variable can be set to the following values: + * + * - "0": Surfaces with a colorkey or an alpha channel are saved to a 32-bit + * BMP file with an alpha mask. SDL will use the bitmap header version 4 and + * set the alpha mask accordingly. (default) + * - "1": Surfaces with a colorkey or an alpha channel are saved to a 32-bit + * BMP file without an alpha mask. The alpha channel data will be in the + * file, but applications are going to ignore it. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_BMP_SAVE_LEGACY_FORMAT = 'SDL_BMP_SAVE_LEGACY_FORMAT'; + +{* + * A variable that decides what camera backend to use. + * + * By default, SDL will try all available camera backends in a reasonable + * order until it finds one that can work, but this hint allows the app or + * user to force a specific target, such as "directshow" if, say, you are on + * Windows Media Foundations but want to try DirectShow instead. + * + * The default value is unset, in which case SDL will try to figure out the + * best camera backend on your behalf. This hint needs to be set before + * SDL_Init() is called to be useful. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_CAMERA_DRIVER = 'SDL_CAMERA_DRIVER'; + +{* + * A variable that limits what CPU features are available. + * + * By default, SDL marks all features the current CPU supports as available. + * This hint allows to limit these to a subset. + * + * When the hint is unset, or empty, SDL will enable all detected CPU + * features. + * + * The variable can be set to a comma separated list containing the following + * items: + * + * - "all" + * - "altivec" + * - "sse" + * - "sse2" + * - "sse3" + * - "sse41" + * - "sse42" + * - "avx" + * - "avx2" + * - "avx512f" + * - "arm-simd" + * - "neon" + * - "lsx" + * - "lasx" + * + * The items can be prefixed by '+'/'-' to add/remove features. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_CPU_FEATURE_MASK = 'SDL_CPU_FEATURE_MASK'; + +{* + * A variable controlling whether DirectInput should be used for controllers. + * + * The variable can be set to the following values: + * + * - "0": Disable DirectInput detection. + * - "1": Enable DirectInput detection. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_DIRECTINPUT = 'SDL_JOYSTICK_DIRECTINPUT'; + +{* + * A variable that specifies a dialog backend to use. + * + * By default, SDL will try all available dialog backends in a reasonable + * order until it finds one that can work, but this hint allows the app or + * user to force a specific target. + * + * If the specified target does not exist or is not available, the + * dialog-related function calls will fail. + * + * This hint currently only applies to platforms using the generic "Unix" + * dialog implementation, but may be extended to more platforms in the future. + * Note that some Unix and Unix-like platforms have their own implementation, + * such as macOS and Haiku. + * + * The variable can be set to the following values: + * + * - nil: Select automatically (default, all platforms) + * - "portal": Use XDG Portals through DBus (Unix only) + * - "zenity": Use the Zenity program (Unix only) + * + * More options may be added in the future. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_FILE_DIALOG_DRIVER = 'SDL_FILE_DIALOG_DRIVER'; + +{* + * Override for SDL_GetDisplayUsableBounds(). + * + * If set, this hint will override the expected results for + * SDL_GetDisplayUsableBounds() for display index 0. Generally you don't want + * to do this, but this allows an embedded system to request that some of the + * screen be reserved for other uses when paired with a well-behaved + * application. + * + * The contents of this hint must be 4 comma-separated integers, the first is + * the bounds x, then y, width and height, in that order. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_DISPLAY_USABLE_BOUNDS = 'SDL_DISPLAY_USABLE_BOUNDS'; + +{* + * Disable giving back control to the browser automatically when running with + * asyncify. + * + * With -s ASYNCIFY, SDL calls emscripten_sleep during operations such as + * refreshing the screen or polling events. + * + * This hint only applies to the emscripten platform. + * + * The variable can be set to the following values: + * + * - "0": Disable emscripten_sleep calls (if you give back browser control + * manually or use asyncify for other purposes). + * - "1": Enable emscripten_sleep calls. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_EMSCRIPTEN_ASYNCIFY = 'SDL_EMSCRIPTEN_ASYNCIFY'; + +{* + * Specify the CSS selector used for the "default" window/canvas. + * + * This hint only applies to the emscripten platform. + * + * The default value is "#canvas" + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_EMSCRIPTEN_CANVAS_SELECTOR = 'SDL_EMSCRIPTEN_CANVAS_SELECTOR'; + +{* + * Override the binding element for keyboard inputs for Emscripten builds. + * + * This hint only applies to the emscripten platform. + * + * The variable can be one of: + * + * - "#window": the javascript window object (default) + * - "#document": the javascript document object + * - "#screen": the javascript window.screen object + * - "#canvas": the WebGL canvas element + * - "#none": Don't bind anything at all + * - any other string without a leading # sign applies to the element on the + * page with that ID. + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_EMSCRIPTEN_KEYBOARD_ELEMENT = 'SDL_EMSCRIPTEN_KEYBOARD_ELEMENT'; + +{* + * A variable that controls whether the on-screen keyboard should be shown + * when text input is active. + * + * The variable can be set to the following values: + * + * - "auto": The on-screen keyboard will be shown if there is no physical + * keyboard attached. (default) + * - "0": Do not show the on-screen keyboard. + * - "1": Show the on-screen keyboard, if available. + * + * This hint must be set before SDL_StartTextInput() is called + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_ENABLE_SCREEN_KEYBOARD = 'SDL_ENABLE_SCREEN_KEYBOARD'; + +{* + * A variable containing a list of evdev devices to use if udev is not + * available. + * + * The list of devices is in the form: + * + * deviceclass: path[,deviceclass: path[,...]] + * + * where device class is an integer representing the SDL_UDEV_deviceclass and + * path is the full path to the event device. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_EVDEV_DEVICES = 'SDL_EVDEV_DEVICES'; + +{* + * A variable controlling verbosity of the logging of SDL events pushed onto + * the internal queue. + * + * The variable can be set to the following values, from least to most + * verbose: + * + * - "0": Don't log any events. (default) + * - "1": Log most events (other than the really spammy ones). + * - "2": Include mouse and finger motion events. + * + * This is generally meant to be used to debug SDL itself, but can be useful + * for application developers that need better visibility into what is going + * on in the event queue. Logged events are sent through SDL_Log(), which + * means by default they appear on stdout on most platforms or maybe + * OutputDebugString() on Windows, and can be funneled by the app with + * SDL_SetLogOutputFunction(), etc. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_EVENT_LOGGING = 'SDL_EVENT_LOGGING'; + +{* + * A variable controlling whether raising the window should be done more + * forcefully. + * + * The variable can be set to the following values: + * + * - "0": Honor the OS policy for raising windows. (default) + * - "1": Force the window to be raised, overriding any OS policy. + * + * At present, this is only an issue under MS Windows, which makes it nearly + * impossible to programmatically move a window to the foreground, for + * "security" reasons. See http://stackoverflow.com/a/34414846 for a + * discussion. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_FORCE_RAISEWINDOW = 'SDL_FORCE_RAISEWINDOW'; + +{* + * A variable controlling how 3D acceleration is used to accelerate the SDL + * screen surface. + * + * SDL can try to accelerate the SDL screen surface by using streaming + * textures with a 3D rendering engine. This variable controls whether and how + * this is done. + * + * The variable can be set to the following values: + * + * - "0": Disable 3D acceleration + * - "1": Enable 3D acceleration, using the default renderer. (default) + * - "X": Enable 3D acceleration, using X where X is one of the valid + * rendering drivers. (e.g. "direct3d", "opengl", etc.) + * + * This hint should be set before calling SDL_GetWindowSurface() + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_FRAMEBUFFER_ACCELERATION = 'SDL_FRAMEBUFFER_ACCELERATION'; + +{* + * A variable that lets you manually hint extra gamecontroller db entries. + * + * The variable should be newline delimited rows of gamecontroller config + * data, see SDL_gamepad.h + * + * You can update mappings after SDL is initialized with + * SDL_GetGamepadMappingForGUID() and SDL_AddGamepadMapping() + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_GAMECONTROLLERCONFIG = 'SDL_GAMECONTROLLERCONFIG'; + +{* + * A variable that lets you provide a file with extra gamecontroller db + * entries. + * + * The file should contain lines of gamecontroller config data, see + * SDL_gamepad.h + * + * You can update mappings after SDL is initialized with + * SDL_GetGamepadMappingForGUID() and SDL_AddGamepadMapping() + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_GAMECONTROLLERCONFIG_FILE = 'SDL_GAMECONTROLLERCONFIG_FILE'; + +{* + * A variable that overrides the automatic controller type detection. + * + * The variable should be comma separated entries, in the form: VID/PID=type + * + * The VID and PID should be hexadecimal with exactly 4 digits, e.g. 0x00fd + * + * This hint affects what low level protocol is used with the HIDAPI driver. + * + * The variable can be set to the following values: + * + * - "Xbox360" + * - "XboxOne" + * - "PS3" + * - "PS4" + * - "PS5" + * - "SwitchPro" + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_GAMECONTROLLERTYPE = 'SDL_GAMECONTROLLERTYPE'; + +{* + * A variable containing a list of devices to skip when scanning for game + * controllers. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES = 'SDL_GAMECONTROLLER_IGNORE_DEVICES'; + +{* + * If set, all devices will be skipped when scanning for game controllers + * except for the ones listed in this variable. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT = 'SDL_GAMECONTROLLER_IGNORE_DEVICES_EXCEPT'; + +{* + * A variable that controls whether the device's built-in accelerometer and + * gyro should be used as sensors for gamepads. + * + * The variable can be set to the following values: + * + * - "0": Sensor fusion is disabled + * - "1": Sensor fusion is enabled for all controllers that lack sensors + * + * Or the variable can be a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * 0xAAAA/0xBBBB,0xCCCC/0xDDDD + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint should be set before a gamepad is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_GAMECONTROLLER_SENSOR_FUSION = 'SDL_GAMECONTROLLER_SENSOR_FUSION'; + +{* + * This variable sets the default text of the TextInput window on GDK + * platforms. + * + * This hint is available only if SDL_GDK_TEXTINPUT defined. + * + * This hint should be set before calling SDL_StartTextInput() + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_GDK_TEXTINPUT_DEFAULT_TEXT = 'SDL_GDK_TEXTINPUT_DEFAULT_TEXT'; + +{* + * This variable sets the description of the TextInput window on GDK + * platforms. + * + * This hint is available only if SDL_GDK_TEXTINPUT defined. + * + * This hint should be set before calling SDL_StartTextInput() + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_GDK_TEXTINPUT_DESCRIPTION = 'SDL_GDK_TEXTINPUT_DESCRIPTION'; + +{* + * This variable sets the maximum input length of the TextInput window on GDK + * platforms. + * + * The value must be a stringified integer, for example "10" to allow for up + * to 10 characters of text input. + * + * This hint is available only if SDL_GDK_TEXTINPUT defined. + * + * This hint should be set before calling SDL_StartTextInput() + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_GDK_TEXTINPUT_MAX_LENGTH = 'SDL_GDK_TEXTINPUT_MAX_LENGTH'; + +{* + * This variable sets the input scope of the TextInput window on GDK + * platforms. + * + * Set this hint to change the XGameUiTextEntryInputScope value that will be + * passed to the window creation function. The value must be a stringified + * integer, for example "0" for XGameUiTextEntryInputScope:: Default. + * + * This hint is available only if SDL_GDK_TEXTINPUT defined. + * + * This hint should be set before calling SDL_StartTextInput() + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_GDK_TEXTINPUT_SCOPE = 'SDL_GDK_TEXTINPUT_SCOPE'; + +{* + * This variable sets the title of the TextInput window on GDK platforms. + * + * This hint is available only if SDL_GDK_TEXTINPUT defined. + * + * This hint should be set before calling SDL_StartTextInput() + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_GDK_TEXTINPUT_TITLE = 'SDL_GDK_TEXTINPUT_TITLE'; + +{* + * A variable to control whether HIDAPI uses libusb for device access. + * + * By default libusb will only be used for a few devices that require direct + * USB access, and this can be controlled with + * SDL_HINT_HIDAPI_LIBUSB_WHITELIST. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI will not use libusb for device access. + * - "1": HIDAPI will use libusb for device access if available. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_HIDAPI_LIBUSB = 'SDL_HIDAPI_LIBUSB'; + +{* + * A variable to control whether HIDAPI uses libusb only for whitelisted + * devices. + * + * By default libusb will only be used for a few devices that require direct + * USB access. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI will use libusb for all device access. + * - "1": HIDAPI will use libusb only for whitelisted devices. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_HIDAPI_LIBUSB_WHITELIST = 'SDL_HIDAPI_LIBUSB_WHITELIST'; + +{* + * A variable to control whether HIDAPI uses udev for device detection. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI will poll for device changes. + * - "1": HIDAPI will use udev for device detection. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + 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 any GPU functions are called. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_GPU_DRIVER = 'SDL_GPU_DRIVER'; + +{* + * A variable to control whether SDL_hid_enumerate() enumerates all HID + * devices or only controllers. + * + * The variable can be set to the following values: + * + * - "0": SDL_hid_enumerate() will enumerate all HID devices. + * - "1": SDL_hid_enumerate() will only enumerate controllers. (default) + * + * By default SDL will only enumerate controllers, to reduce risk of hanging + * or crashing on devices with bad drivers and avoiding macOS keyboard capture + * permission prompts. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_HIDAPI_ENUMERATE_ONLY_CONTROLLERS = 'SDL_HIDAPI_ENUMERATE_ONLY_CONTROLLERS'; + +{* + * A variable containing a list of devices to ignore in SDL_hid_enumerate(). + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * For example, to ignore the Shanwan DS3 controller and any Valve controller, + * you might use the string "0x2563/0x0523,0x28de/0x0000" + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_HIDAPI_IGNORE_DEVICES = 'SDL_HIDAPI_IGNORE_DEVICES'; + +{* + * A variable describing what IME UI elements the application can display. + * + * By default IME UI is handled using native components by the OS where + * possible, however this can interfere with or not be visible when exclusive + * fullscreen mode is used. + * + * The variable can be set to a comma separated list containing the following + * items: + * + * - "none" or "0": The application can't render any IME elements, and native + * UI should be used. (default) + * - "composition": The application handles SDL_EVENT_TEXT_EDITING events and + * can render the composition text. + * - "candidates": The application handles SDL_EVENT_TEXT_EDITING_CANDIDATES + * and can render the candidate list. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_IME_IMPLEMENTED_UI = 'SDL_IME_IMPLEMENTED_UI'; + +{* + * A variable controlling whether the home indicator bar on iPhone X should be + * hidden. + * + * The variable can be set to the following values: + * + * - "0": The indicator bar is not hidden. (default for windowed applications) + * - "1": The indicator bar is hidden and is shown when the screen is touched + * (useful for movie playback applications). + * - "2": The indicator bar is dim and the first swipe makes it visible and + * the second swipe performs the "home" action. (default for fullscreen + * applications) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_IOS_HIDE_HOME_INDICATOR = 'SDL_IOS_HIDE_HOME_INDICATOR'; + +{* + * A variable that lets you enable joystick (and gamecontroller) events even + * when your app is in the background. + * + * The variable can be set to the following values: + * + * - "0": Disable joystick & gamecontroller input events when the application + * is in the background. (default) + * - "1": Enable joystick & gamecontroller input events when the application + * is in the background. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_ALLOW_BACKGROUND_EVENTS = 'SDL_JOYSTICK_ALLOW_BACKGROUND_EVENTS'; + +{* + * A variable containing a list of arcade stick style controllers. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES = 'SDL_JOYSTICK_ARCADESTICK_DEVICES'; + +{* + * A variable containing a list of devices that are not arcade stick style + * controllers. + * + * This will override SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES and the built in + * device list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED = 'SDL_JOYSTICK_ARCADESTICK_DEVICES_EXCLUDED'; + +{* + * A variable containing a list of devices that should not be considered + * joysticks. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_BLACKLIST_DEVICES = 'SDL_JOYSTICK_BLACKLIST_DEVICES'; + +{* + * A variable containing a list of devices that should be considered + * joysticks. + * + * This will override SDL_HINT_JOYSTICK_BLACKLIST_DEVICES and the built in + * device list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED = 'SDL_JOYSTICK_BLACKLIST_DEVICES_EXCLUDED'; + +{* + * A variable containing a comma separated list of devices to open as + * joysticks. + * + * This variable is currently only used by the Linux joystick driver. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_DEVICE = 'SDL_JOYSTICK_DEVICE'; + +{* + * A variable controlling whether enhanced reports should be used for + * controllers when using the HIDAPI driver. + * + * Enhanced reports allow rumble and effects on Bluetooth PlayStation + * controllers and gyro on Nintendo Switch controllers, but break Windows + * DirectInput for other applications that don't use SDL. + * + * Once enhanced reports are enabled, they can't be disabled on PlayStation + * controllers without power cycling the controller. + * + * The variable can be set to the following values: + * + * - "0": enhanced reports are not enabled. + * - "1": enhanced reports are enabled. (default) + * - "auto": enhanced features are advertised to the application, but SDL + * doesn't change the controller report mode unless the application uses + * them. + * + * This hint can be enabled anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_ENHANCED_REPORTS = 'SDL_JOYSTICK_ENHANCED_REPORTS'; + +{* + * A variable containing a list of flightstick style controllers. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of @file, in which case the named file + * will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES = 'SDL_JOYSTICK_FLIGHTSTICK_DEVICES'; + +{* + * A variable containing a list of devices that are not flightstick style + * controllers. + * + * This will override SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES and the built in + * device list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED = 'SDL_JOYSTICK_FLIGHTSTICK_DEVICES_EXCLUDED'; + +{* + * A variable controlling whether GameInput should be used for controller + * handling on Windows. + * + * The variable can be set to the following values: + * + * - "0": GameInput is not used. + * - "1": GameInput is used. + * + * The default is "1" on GDK platforms, and "0" otherwise. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_GAMEINPUT = 'SDL_JOYSTICK_GAMEINPUT'; + +{* + * A variable containing a list of devices known to have a GameCube form + * factor. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_GAMECUBE_DEVICES = 'SDL_JOYSTICK_GAMECUBE_DEVICES'; + +{* + * A variable containing a list of devices known not to have a GameCube form + * factor. + * + * This will override SDL_HINT_JOYSTICK_GAMECUBE_DEVICES and the built in + * device list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED = 'SDL_JOYSTICK_GAMECUBE_DEVICES_EXCLUDED'; + +{* + * A variable controlling whether the HIDAPI joystick drivers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI drivers are not used. + * - "1": HIDAPI drivers are used. (default) + * + * This variable is the default for all drivers, but can be overridden by the + * hints for specific drivers below. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI = 'SDL_JOYSTICK_HIDAPI'; + +{* + * A variable controlling whether Nintendo Switch Joy-Con controllers will be + * combined into a single Pro-like controller when using the HIDAPI driver. + * + * The variable can be set to the following values: + * + * - "0": Left and right Joy-Con controllers will not be combined and each + * will be a mini-gamepad. + * - "1": Left and right Joy-Con controllers will be combined into a single + * controller. (default) + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_COMBINE_JOY_CONS = 'SDL_JOYSTICK_HIDAPI_COMBINE_JOY_CONS'; + +{* + * A variable controlling whether the HIDAPI driver for Nintendo GameCube + * controllers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE = 'SDL_JOYSTICK_HIDAPI_GAMECUBE'; + +{* + * A variable controlling whether rumble is used to implement the GameCube + * controller's 3 rumble modes, Stop(0), Rumble(1), and StopHard(2). + * + * This is useful for applications that need full compatibility for things + * like ADSR envelopes. - Stop is implemented by setting low_frequency_rumble + * to 0 and high_frequency_rumble >0 - Rumble is both at any arbitrary value - + * StopHard is implemented by setting both low_frequency_rumble and + * high_frequency_rumble to 0 + * + * The variable can be set to the following values: + * + * - "0": Normal rumble behavior is behavior is used. (default) + * - "1": Proper GameCube controller rumble behavior is used. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE = 'SDL_JOYSTICK_HIDAPI_GAMECUBE_RUMBLE_BRAKE'; + +{* + * A variable controlling whether the HIDAPI driver for Nintendo Switch + * Joy-Cons should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_JOY_CONS = 'SDL_JOYSTICK_HIDAPI_JOY_CONS'; + +{* + * A variable controlling whether the Home button LED should be turned on when + * a Nintendo Switch Joy-Con controller is opened. + * + * The variable can be set to the following values: + * + * - "0": home button LED is turned off + * - "1": home button LED is turned on + * + * By default the Home button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Home button LED. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_JOYCON_HOME_LED = 'SDL_JOYSTICK_HIDAPI_JOYCON_HOME_LED'; + +{* + * A variable controlling whether the HIDAPI driver for Amazon Luna + * controllers connected via Bluetooth should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_LUNA = 'SDL_JOYSTICK_HIDAPI_LUNA'; + +{* + * A variable controlling whether the HIDAPI driver for Nintendo Online + * classic controllers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_NINTENDO_CLASSIC = 'SDL_JOYSTICK_HIDAPI_NINTENDO_CLASSIC'; + +{* + * A variable controlling whether the HIDAPI driver for PS3 controllers should + * be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI on macOS, and "0" on + * other platforms. + * + * For official Sony driver (sixaxis.sys) use + * SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER. See + * https://github.com/ViGEm/DsHidMini for an alternative driver on Windows. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_PS3 = 'SDL_JOYSTICK_HIDAPI_PS3'; + +{* + * A variable controlling whether the Sony driver (sixaxis.sys) for PS3 + * controllers (Sixaxis/DualShock 3) should be used. + * + * The variable can be set to the following values: + * + * - "0": Sony driver (sixaxis.sys) is not used. + * - "1": Sony driver (sixaxis.sys) is used. + * + * The default value is 0. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER = 'SDL_JOYSTICK_HIDAPI_PS3_SIXAXIS_DRIVER'; + +{* + * A variable controlling whether the HIDAPI driver for PS4 controllers should + * be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_PS4 = 'SDL_JOYSTICK_HIDAPI_PS4'; + +{* + * A variable controlling the update rate of the PS4 controller over Bluetooth + * when using the HIDAPI driver. + * + * This defaults to 4 ms, to match the behavior over USB, and to be more + * friendly to other Bluetooth devices and older Bluetooth hardware on the + * computer. It can be set to "1" (1000Hz), "2" (500Hz) and "4" (250Hz) + * + * This hint can be set anytime, but only takes effect when extended input + * reports are enabled. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_PS4_REPORT_INTERVAL = 'SDL_JOYSTICK_HIDAPI_PS4_REPORT_INTERVAL'; + +{* + * A variable controlling whether the HIDAPI driver for PS5 controllers should + * be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_PS5 = 'SDL_JOYSTICK_HIDAPI_PS5'; + +{* + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with a PS5 controller. + * + * The variable can be set to the following values: + * + * - "0": player LEDs are not enabled. + * - "1": player LEDs are enabled. (default) + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_PS5_PLAYER_LED = 'SDL_JOYSTICK_HIDAPI_PS5_PLAYER_LED'; + +{* + * A variable controlling whether the HIDAPI driver for NVIDIA SHIELD + * controllers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_SHIELD = 'SDL_JOYSTICK_HIDAPI_SHIELD'; + +{* + * A variable controlling whether the HIDAPI driver for Google Stadia + * controllers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_STADIA = 'SDL_JOYSTICK_HIDAPI_STADIA'; + +{* + * A variable controlling whether the HIDAPI driver for Bluetooth Steam + * Controllers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. (default) + * - "1": HIDAPI driver is used for Steam Controllers, which requires + * Bluetooth access and may prompt the user for permission on iOS and + * Android. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_STEAM = 'SDL_JOYSTICK_HIDAPI_STEAM'; + +{* + * A variable controlling whether the Steam button LED should be turned on + * when a Steam controller is opened. + * + * The variable can be set to the following values: + * + * - "0": Steam button LED is turned off. + * - "1": Steam button LED is turned on. + * + * By default the Steam button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Steam button LED. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_STEAM_HOME_LED = 'SDL_JOYSTICK_HIDAPI_STEAM_HOME_LED'; + +{* + * A variable controlling whether the HIDAPI driver for the Steam Deck builtin + * controller should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + 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 + } + SDL_HINT_JOYSTICK_HIDAPI_STEAM_HORI = 'SDL_JOYSTICK_HIDAPI_STEAM_HORI'; + +{* + * A variable controlling whether the HIDAPI driver for Nintendo Switch + * controllers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_SWITCH = 'SDL_JOYSTICK_HIDAPI_SWITCH'; + +{* + * A variable controlling whether the Home button LED should be turned on when + * a Nintendo Switch Pro controller is opened. + * + * The variable can be set to the following values: + * + * - "0": Home button LED is turned off. + * - "1": Home button LED is turned on. + * + * By default the Home button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Home button LED. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_SWITCH_HOME_LED = 'SDL_JOYSTICK_HIDAPI_SWITCH_HOME_LED'; + +{* + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with a Nintendo Switch controller. + * + * The variable can be set to the following values: + * + * - "0": Player LEDs are not enabled. + * - "1": Player LEDs are enabled. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED = 'SDL_JOYSTICK_HIDAPI_SWITCH_PLAYER_LED'; + +{* + * A variable controlling whether Nintendo Switch Joy-Con controllers will be + * in vertical mode when using the HIDAPI driver. + * + * The variable can be set to the following values: + * + * - "0": Left and right Joy-Con controllers will not be in vertical mode. + * (default) + * - "1": Left and right Joy-Con controllers will be in vertical mode. + * + * This hint should be set before opening a Joy-Con controller. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS = 'SDL_JOYSTICK_HIDAPI_VERTICAL_JOY_CONS'; + +{* + * A variable controlling whether the HIDAPI driver for Nintendo Wii and Wii U + * controllers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * This driver doesn't work with the dolphinbar, so the default is false for + * now. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_WII = 'SDL_JOYSTICK_HIDAPI_WII'; + +{* + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with a Wii controller. + * + * The variable can be set to the following values: + * + * - "0": Player LEDs are not enabled. + * - "1": Player LEDs are enabled. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_WII_PLAYER_LED = 'SDL_JOYSTICK_HIDAPI_WII_PLAYER_LED'; + +{* + * A variable controlling whether the HIDAPI driver for XBox controllers + * should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is "0" on Windows, otherwise the value of + * SDL_HINT_JOYSTICK_HIDAPI + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_XBOX = 'SDL_JOYSTICK_HIDAPI_XBOX'; + +{* + * A variable controlling whether the HIDAPI driver for XBox 360 controllers + * should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 = 'SDL_JOYSTICK_HIDAPI_XBOX_360'; + +{* + * A variable controlling whether the player LEDs should be lit to indicate + * which player is associated with an Xbox 360 controller. + * + * The variable can be set to the following values: + * + * - "0": Player LEDs are not enabled. + * - "1": Player LEDs are enabled. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED = 'SDL_JOYSTICK_HIDAPI_XBOX_360_PLAYER_LED'; + +{* + * A variable controlling whether the HIDAPI driver for XBox 360 wireless + * controllers should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX_360 + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_XBOX_360_WIRELESS = 'SDL_JOYSTICK_HIDAPI_XBOX_360_WIRELESS'; + +{* + * A variable controlling whether the HIDAPI driver for XBox One controllers + * should be used. + * + * The variable can be set to the following values: + * + * - "0": HIDAPI driver is not used. + * - "1": HIDAPI driver is used. + * + * The default is the value of SDL_HINT_JOYSTICK_HIDAPI_XBOX. + * + * This hint should be set before initializing joysticks and gamepads. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE = 'SDL_JOYSTICK_HIDAPI_XBOX_ONE'; + +{* + * A variable controlling whether the Home button LED should be turned on when + * an Xbox One controller is opened. + * + * The variable can be set to the following values: + * + * - "0": Home button LED is turned off. + * - "1": Home button LED is turned on. + * + * By default the Home button LED state is not changed. This hint can also be + * set to a floating point value between 0.0 and 1.0 which controls the + * brightness of the Home button LED. The default brightness is 0.4. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED = 'SDL_JOYSTICK_HIDAPI_XBOX_ONE_HOME_LED'; + +{* + * A variable controlling whether IOKit should be used for controller + * handling. + * + * The variable can be set to the following values: + * + * - "0": IOKit is not used. + * - "1": IOKit is used. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_IOKIT = 'SDL_JOYSTICK_IOKIT'; + +{* + * A variable controlling whether to use the classic /dev/input/js* joystick + * interface or the newer /dev/input/event* joystick interface on Linux. + * + * The variable can be set to the following values: + * + * - "0": Use /dev/input/event* (default) + * - "1": Use /dev/input/js* + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_LINUX_CLASSIC = 'SDL_JOYSTICK_LINUX_CLASSIC'; + +{* + * A variable controlling whether joysticks on Linux adhere to their + * HID-defined deadzones or return unfiltered values. + * + * The variable can be set to the following values: + * + * - "0": Return unfiltered joystick axis values. (default) + * - "1": Return axis values with deadzones taken into account. + * + * This hint should be set before a controller is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_LINUX_DEADZONES = 'SDL_JOYSTICK_LINUX_DEADZONES'; + +{* + * A variable controlling whether joysticks on Linux will always treat 'hat' + * axis inputs (ABS_HAT0X - ABS_HAT3Y) as 8-way digital hats without checking + * whether they may be analog. + * + * The variable can be set to the following values: + * + * - "0": Only map hat axis inputs to digital hat outputs if the input axes + * appear to actually be digital. (default) + * - "1": Always handle the input axes numbered ABS_HAT0X to ABS_HAT3Y as + * digital hats. + * + * This hint should be set before a controller is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_LINUX_DIGITAL_HATS = 'SDL_JOYSTICK_LINUX_DIGITAL_HATS'; + +{* + * A variable controlling whether digital hats on Linux will apply deadzones + * to their underlying input axes or use unfiltered values. + * + * The variable can be set to the following values: + * + * - "0": Return digital hat values based on unfiltered input axis values. + * - "1": Return digital hat values with deadzones on the input axes taken + * into account. (default) + * + * This hint should be set before a controller is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_LINUX_HAT_DEADZONES = 'SDL_JOYSTICK_LINUX_HAT_DEADZONES'; + +{* + * A variable controlling whether GCController should be used for controller + * handling. + * + * The variable can be set to the following values: + * + * - "0": GCController is not used. + * - "1": GCController is used. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_MFI = 'SDL_JOYSTICK_MFI'; + +{* + * A variable controlling whether the RAWINPUT joystick drivers should be used + * for better handling XInput-capable devices. + * + * The variable can be set to the following values: + * + * - "0": RAWINPUT drivers are not used. + * - "1": RAWINPUT drivers are used. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_RAWINPUT = 'SDL_JOYSTICK_RAWINPUT'; + +{* + * A variable controlling whether the RAWINPUT driver should pull correlated + * data from XInput. + * + * The variable can be set to the following values: + * + * - "0": RAWINPUT driver will only use data from raw input APIs. + * - "1": RAWINPUT driver will also pull data from XInput and + * Windows.Gaming.Input, providing better trigger axes, guide button + * presses, and rumble support for Xbox controllers. (default) + * + * This hint should be set before a gamepad is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_RAWINPUT_CORRELATE_XINPUT = 'SDL_JOYSTICK_RAWINPUT_CORRELATE_XINPUT'; + +{* + * A variable controlling whether the ROG Chakram mice should show up as + * joysticks. + * + * The variable can be set to the following values: + * + * - "0": ROG Chakram mice do not show up as joysticks. (default) + * - "1": ROG Chakram mice show up as joysticks. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_ROG_CHAKRAM = 'SDL_JOYSTICK_ROG_CHAKRAM'; + +{* + * A variable controlling whether a separate thread should be used for + * handling joystick detection and raw input messages on Windows. + * + * The variable can be set to the following values: + * + * - "0": A separate thread is not used. + * - "1": A separate thread is used for handling raw input messages. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_THREAD = 'SDL_JOYSTICK_THREAD'; + +{* + * A variable containing a list of throttle style controllers. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_THROTTLE_DEVICES = 'SDL_JOYSTICK_THROTTLE_DEVICES'; + +{* + * A variable containing a list of devices that are not throttle style + * controllers. + * + * This will override SDL_HINT_JOYSTICK_THROTTLE_DEVICES and the built in + * device list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_THROTTLE_DEVICES_EXCLUDED = 'SDL_JOYSTICK_THROTTLE_DEVICES_EXCLUDED'; + +{* + * A variable controlling whether Windows.Gaming.Input should be used for + * controller handling. + * + * The variable can be set to the following values: + * + * - "0": WGI is not used. + * - "1": WGI is used. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_WGI = 'SDL_JOYSTICK_WGI'; + +{* + * A variable containing a list of wheel style controllers. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_WHEEL_DEVICES = 'SDL_JOYSTICK_WHEEL_DEVICES'; + +{* + * A variable containing a list of devices that are not wheel style + * controllers. + * + * This will override SDL_HINT_JOYSTICK_WHEEL_DEVICES and the built in device + * list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_WHEEL_DEVICES_EXCLUDED = 'SDL_JOYSTICK_WHEEL_DEVICES_EXCLUDED'; + +{* + * A variable containing a list of devices known to have all axes centered at + * zero. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint should be set before a controller is opened. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_JOYSTICK_ZERO_CENTERED_DEVICES = 'SDL_JOYSTICK_ZERO_CENTERED_DEVICES'; + +{* + * A variable that controls keycode representation in keyboard events. + * + * This variable is a comma separated set of options for translating keycodes + * in events: + * + * - "none": Keycode options are cleared, this overrides other options. + * - "hide_numpad": The numpad keysyms will be translated into their + * non-numpad versions based on the current NumLock state. For example, + * SDLK_KP_4 would become SDLK_4 if SDL_KMOD_NUM is set in the event + * modifiers, and SDLK_LEFT if it is unset. + * - "french_numbers": The number row on French keyboards is inverted, so + * pressing the 1 key would yield the keycode SDLK_1, or '1', instead of + * SDLK_AMPERSAND, or '&' + * - "latin_letters": For keyboards using non-Latin letters, such as Russian + * or Thai, the letter keys generate keycodes as though it had an en_US + * layout. e.g. pressing the key associated with SDL_SCANCODE_A on a Russian + * keyboard would yield 'a' instead of a Cyrillic letter. + * + * The default value for this hint is "french_numbers,latin_letters" + * + * Some platforms like Emscripten only provide modified keycodes and the + * options are not used. + * + * These options do not affect the return value of SDL_GetKeyFromScancode() or + * SDL_GetScancodeFromKey(), they just apply to the keycode included in key + * events. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_KEYCODE_OPTIONS = 'SDL_KEYCODE_OPTIONS'; + +{* + * A variable that controls what KMSDRM device to use. + * + * SDL might open something like "/dev/dri/cardNN" to access KMSDRM + * functionality, where "NN" is a device index number. SDL makes a guess at + * the best index to use (usually zero), but the app or user can set this hint + * to a number between 0 and 99 to force selection. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_KMSDRM_DEVICE_INDEX = 'SDL_KMSDRM_DEVICE_INDEX'; + +{* + * A variable that controls whether SDL requires DRM master access in order to + * initialize the KMSDRM video backend. + * + * The DRM subsystem has a concept of a "DRM master" which is a DRM client + * that has the ability to set planes, set cursor, etc. When SDL is DRM + * master, it can draw to the screen using the SDL rendering APIs. Without DRM + * master, SDL is still able to process input and query attributes of attached + * displays, but it cannot change display state or draw to the screen + * directly. + * + * In some cases, it can be useful to have the KMSDRM backend even if it + * cannot be used for rendering. An app may want to use SDL for input + * processing while using another rendering API (such as an MMAL overlay on + * Raspberry Pi) or using its own code to render to DRM overlays that SDL + * doesn't support. + * + * The variable can be set to the following values: + * + * - "0": SDL will allow usage of the KMSDRM backend without DRM master. + * - "1": SDL Will require DRM master to use the KMSDRM backend. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_KMSDRM_REQUIRE_DRM_MASTER = 'SDL_KMSDRM_REQUIRE_DRM_MASTER'; + +{* + * A variable controlling the default SDL log levels. + * + * This variable is a comma separated set of category=level tokens that define + * the default logging levels for SDL applications. + * + * The category can be a numeric category, one of "app", "error", "assert", + * "system", "audio", "video", "render", "input", "test", or `*` for any + * unspecified category. + * + * The level can be a numeric level, one of "verbose", "debug", "info", + * "warn", "error", "critical", or "quiet" to disable that category. + * + * You can omit the category if you want to set the logging level for all + * categories. + * + * If this hint isn't set, the default log levels are equivalent to: + * + * `app=info,assert=warn,test=verbose,*=error` + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_LOGGING = 'SDL_LOGGING'; + +{* + * A variable controlling whether to force the application to become the + * foreground process when launched on macOS. + * + * The variable can be set to the following values: + * + * - "0": The application is brought to the foreground when launched. + * (default) + * - "1": The application may remain in the background when launched. + * + * This hint needs to be set before SDL_Init(). + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MAC_BACKGROUND_APP = 'SDL_MAC_BACKGROUND_APP'; + +{* + * A variable that determines whether Ctrl+Click should generate a right-click + * event on macOS. + * + * The variable can be set to the following values: + * + * - "0": Ctrl+Click does not generate a right mouse button click event. + * (default) + * - "1": Ctrl+Click generated a right mouse button click event. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK = 'SDL_MAC_CTRL_CLICK_EMULATE_RIGHT_CLICK'; + +{* + * A variable controlling whether dispatching OpenGL context updates should + * block the dispatching thread until the main thread finishes processing on + * macOS. + * + * The variable can be set to the following values: + * + * - "0": Dispatching OpenGL context updates will block the dispatching thread + * until the main thread finishes processing. (default) + * - "1": Dispatching OpenGL context updates will allow the dispatching thread + * to continue execution. + * + * Generally you want the default, but if you have OpenGL code in a background + * thread on a Mac, and the main thread hangs because it's waiting for that + * background thread, but that background thread is also hanging because it's + * waiting for the main thread to do an update, this might fix your issue. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MAC_OPENGL_ASYNC_DISPATCH = 'SDL_MAC_OPENGL_ASYNC_DISPATCH'; + +{* + * A variable controlling whether the Option (⌥) key on macOS should be + * remapped to act as the Alt key. + * + * The variable can be set to the following values: + * + * - "none": The Option key is not remapped to Alt. (default) + * - "only_left": Only the left Option key is remapped to Alt. + * - "only_right": Only the right Option key is remapped to Alt. + * - "both": Both Option keys are remapped to Alt. + * + * This will prevent the triggering of key compositions that rely on the + * Option key, but will still send the Alt modifier for keyboard events. In + * the case that both Alt and Option are pressed, the Option key will be + * ignored. This is particularly useful for applications like terminal + * emulators and graphical user interfaces (GUIs) that rely on Alt key + * functionality for shortcuts or navigation. This does not apply to + * SDL_GetKeyFromScancode and only has an effect if IME is enabled. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MAC_OPTION_AS_ALT = 'SDL_MAC_OPTION_AS_ALT'; + +{* + * A variable controlling whether SDL_EVENT_MOUSE_WHEEL event values will have + * momentum on macOS. + * + * The variable can be set to the following values: + * + * - "0": The mouse wheel events will have no momentum. (default) + * - "1": The mouse wheel events will have momentum. + * + * This hint needs to be set before SDL_Init(). + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MAC_SCROLL_MOMENTUM = 'SDL_MAC_SCROLL_MOMENTUM'; + +{* + * Request SDL_AppIterate() be called at a specific rate. + * + * If this is set to a number, it represents Hz, so "60" means try to iterate + * 60 times per second. "0" means to iterate as fast as possible. Negative + * values are illegal, but reserved, in case they are useful in a future + * revision of SDL. + * + * There are other strings that have special meaning. If set to "waitevent", + * SDL_AppIterate will not be called until new event(s) have arrived (and been + * processed by SDL_AppEvent). This can be useful for apps that are completely + * idle except in response to input. + * + * On some platforms, or if you are using SDL_main instead of SDL_AppIterate, + * this hint is ignored. When the hint can be used, it is allowed to be + * changed at any time. + * + * This defaults to 0, and specifying nil for the hint's value will restore + * the default. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MAIN_CALLBACK_RATE = 'SDL_MAIN_CALLBACK_RATE'; + +{* + * A variable controlling whether the mouse is captured while mouse buttons + * are pressed. + * + * The variable can be set to the following values: + * + * - "0": The mouse is not captured while mouse buttons are pressed. + * - "1": The mouse is captured while mouse buttons are pressed. + * + * By default the mouse is captured while mouse buttons are pressed so if the + * mouse is dragged outside the window, the application continues to receive + * mouse events until the button is released. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MOUSE_AUTO_CAPTURE = 'SDL_MOUSE_AUTO_CAPTURE'; + +{* + * A variable setting the double click radius, in pixels. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MOUSE_DOUBLE_CLICK_RADIUS = 'SDL_MOUSE_DOUBLE_CLICK_RADIUS'; + +{* + * A variable setting the double click time, in milliseconds. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MOUSE_DOUBLE_CLICK_TIME = 'SDL_MOUSE_DOUBLE_CLICK_TIME'; + +{* + * A variable setting which system cursor to use as the default cursor. + * + * This should be an integer corresponding to the SDL_SystemCursor enum. The + * default value is zero (SDL_SYSTEM_CURSOR_DEFAULT). + * + * This hint needs to be set before SDL_Init(). + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MOUSE_DEFAULT_SYSTEM_CURSOR = 'SDL_MOUSE_DEFAULT_SYSTEM_CURSOR'; + +{* + * A variable controlling whether warping a hidden mouse cursor will activate + * relative mouse mode. + * + * When this hint is set, the mouse cursor is hidden, and multiple warps to + * the window center occur within a short time period, SDL will emulate mouse + * warps using relative mouse mode. This can provide smoother and more + * reliable mouse motion for some older games, which continuously calculate + * the distance travelled by the mouse Pointer and warp it back to the center + * of the window, rather than using relative mouse motion. + * + * Note that relative mouse mode may have different mouse acceleration + * behavior than Pointer warps. + * + * If your application needs to repeatedly warp the hidden mouse cursor at a + * high-frequency for other purposes, it should disable this hint. + * + * The variable can be set to the following values: + * + * - "0": Attempts to warp the mouse will always be made. + * - "1": Some mouse warps will be emulated by forcing relative mouse mode. + * (default) + * + * If not set, this is automatically enabled unless an application uses + * relative mouse mode directly. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MOUSE_EMULATE_WARP_WITH_RELATIVE = 'SDL_MOUSE_EMULATE_WARP_WITH_RELATIVE'; + +{* + * Allow mouse click events when clicking to focus an SDL window. + * + * The variable can be set to the following values: + * + * - "0": Ignore mouse clicks that activate a window. (default) + * - "1": Generate events for mouse clicks that activate a window. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MOUSE_FOCUS_CLICKTHROUGH = 'SDL_MOUSE_FOCUS_CLICKTHROUGH'; + +{* + * A variable setting the speed scale for mouse motion, in floating point, + * when the mouse is not in relative mode. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MOUSE_NORMAL_SPEED_SCALE = 'SDL_MOUSE_NORMAL_SPEED_SCALE'; + +{* + * A variable controlling whether relative mouse mode constrains the mouse to + * the center of the window. + * + * Constraining to the center of the window works better for FPS games and + * when the application is running over RDP. Constraining to the whole window + * works better for 2D games and increases the chance that the mouse will be + * in the correct position when using high DPI mice. + * + * The variable can be set to the following values: + * + * - "0": Relative mouse mode constrains the mouse to the window. + * - "1": Relative mouse mode constrains the mouse to the center of the + * window. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MOUSE_RELATIVE_MODE_CENTER = 'SDL_MOUSE_RELATIVE_MODE_CENTER'; + +{* + * A variable setting the scale for mouse motion, in floating point, when the + * mouse is in relative mode. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE = 'SDL_MOUSE_RELATIVE_SPEED_SCALE'; + +{* + * A variable controlling whether the system mouse acceleration curve is used + * for relative mouse motion. + * + * The variable can be set to the following values: + * + * - "0": Relative mouse motion will be unscaled. (default) + * - "1": Relative mouse motion will be scaled using the system mouse + * acceleration curve. + * + * If SDL_HINT_MOUSE_RELATIVE_SPEED_SCALE is set, that will be applied after + * system speed scale. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MOUSE_RELATIVE_SYSTEM_SCALE = 'SDL_MOUSE_RELATIVE_SYSTEM_SCALE'; + +{* + * A variable controlling whether a motion event should be generated for mouse + * warping in relative mode. + * + * The variable can be set to the following values: + * + * - "0": Warping the mouse will not generate a motion event in relative mode + * - "1": Warping the mouse will generate a motion event in relative mode + * + * By default warping the mouse will not generate motion events in relative + * mode. This avoids the application having to filter out large relative + * motion due to warping. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MOUSE_RELATIVE_WARP_MOTION = 'SDL_MOUSE_RELATIVE_WARP_MOTION'; + +{* + * A variable controlling whether the hardware cursor stays visible when + * relative mode is active. + * + * This variable can be set to the following values: + * + * - "0": The cursor will be hidden while relative mode is active (default) + * - "1": The cursor will remain visible while relative mode is active + * + * Note that for systems without raw hardware inputs, relative mode is + * implemented using warping, so the hardware cursor will visibly warp between + * frames if this is enabled on those systems. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MOUSE_RELATIVE_CURSOR_VISIBLE = 'SDL_MOUSE_RELATIVE_CURSOR_VISIBLE'; + +{* + * A variable controlling whether mouse events should generate synthetic touch + * events. + * + * The variable can be set to the following values: + * + * - "0": Mouse events will not generate touch events. (default for desktop + * platforms) + * - "1": Mouse events will generate touch events. (default for mobile + * platforms, such as Android and iOS) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MOUSE_TOUCH_EVENTS = 'SDL_MOUSE_TOUCH_EVENTS'; + +{* + * A variable controlling whether the keyboard should be muted on the console. + * + * Normally the keyboard is muted while SDL applications are running so that + * keyboard input doesn't show up as key strokes on the console. This hint + * allows you to turn that off for debugging purposes. + * + * The variable can be set to the following values: + * + * - "0": Allow keystrokes to go through to the console. + * - "1": Mute keyboard input so it doesn't show up on the console. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_MUTE_CONSOLE_KEYBOARD = 'SDL_MUTE_CONSOLE_KEYBOARD'; + +{* + * Tell SDL not to catch the SIGINT or SIGTERM signals on POSIX platforms. + * + * The variable can be set to the following values: + * + * - "0": SDL will install a SIGINT and SIGTERM handler, and when it catches a + * signal, convert it into an SDL_EVENT_QUIT event. (default) + * - "1": SDL will not install a signal handler at all. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_NO_SIGNAL_HANDLERS = 'SDL_NO_SIGNAL_HANDLERS'; + +{* + * Specify the OpenGL library to load. + * + * This hint should be set before creating an OpenGL window or creating an + * OpenGL context. If this hint isn't set, SDL will choose a reasonable + * default. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_OPENGL_LIBRARY = 'SDL_OPENGL_LIBRARY'; + +{* + * Specify the EGL library to load. + * + * This hint should be set before creating an OpenGL window or creating an + * OpenGL context. This hint is only considered if SDL is using EGL to manage + * OpenGL contexts. If this hint isn't set, SDL will choose a reasonable + * default. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_EGL_LIBRARY = 'SDL_EGL_LIBRARY'; + +{* + * A variable controlling what driver to use for OpenGL ES contexts. + * + * On some platforms, currently Windows and X11, OpenGL drivers may support + * creating contexts with an OpenGL ES profile. By default SDL uses these + * profiles, when available, otherwise it attempts to load an OpenGL ES + * library, e.g. that provided by the ANGLE project. This variable controls + * whether SDL follows this default behaviour or will always load an OpenGL ES + * library. + * + * Circumstances where this is useful include - Testing an app with a + * particular OpenGL ES implementation, e.g ANGLE, or emulator, e.g. those + * from ARM, Imagination or Qualcomm. - Resolving OpenGL ES function addresses + * at link time by linking with the OpenGL ES library instead of querying them + * at run time with SDL_GL_GetProcAddress(). + * + * Caution: for an application to work with the default behaviour across + * different OpenGL drivers it must query the OpenGL ES function addresses at + * run time using SDL_GL_GetProcAddress(). + * + * This variable is ignored on most platforms because OpenGL ES is native or + * not supported. + * + * The variable can be set to the following values: + * + * - "0": Use ES profile of OpenGL, if available. (default) + * - "1": Load OpenGL ES library using the default library names. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_OPENGL_ES_DRIVER = 'SDL_OPENGL_ES_DRIVER'; + +{* + * Mechanism to specify openvr_api library location + * + * By default, when using the OpenVR driver, it will search for the API + * library in the current folder. But, if you wish to use a system API you can + * specify that by using this hint. This should be the full or relative path + * to a .dll on Windows or .so on Linux. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_OPENVR_LIBRARY = 'SDL_OPENVR_LIBRARY'; + +{* + * A variable controlling which orientations are allowed on iOS/Android. + * + * In some circumstances it is necessary to be able to explicitly control + * which UI orientations are allowed. + * + * This variable is a space delimited list of the following values: + * + * - "LandscapeLeft" + * - "LandscapeRight" + * - "Portrait" + * - "PortraitUpsideDown" + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_ORIENTATIONS = 'SDL_ORIENTATIONS'; + +{* + * A variable controlling the use of a sentinel event when polling the event + * queue. + * + * When polling for events, SDL_PumpEvents is used to gather new events from + * devices. If a device keeps producing new events between calls to + * SDL_PumpEvents, a poll loop will become stuck until the new events stop. + * This is most noticeable when moving a high frequency mouse. + * + * The variable can be set to the following values: + * + * - "0": Disable poll sentinels. + * - "1": Enable poll sentinels. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_POLL_SENTINEL = 'SDL_POLL_SENTINEL'; + +{* + * Override for SDL_GetPreferredLocales(). + * + * If set, this will be favored over anything the OS might report for the + * user's preferred locales. Changing this hint at runtime will not generate a + * SDL_EVENT_LOCALE_CHANGED event (but if you can change the hint, you can + * push your own event, if you want). + * + * The format of this hint is a comma-separated list of language and locale, + * combined with an underscore, as is a common format: "en_GB". Locale is + * optional: "en". So you might have a list like this: "en_GB,jp,es_PT" + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_PREFERRED_LOCALES = 'SDL_PREFERRED_LOCALES'; + +{* + * A variable that decides whether to send SDL_EVENT_QUIT when closing the + * last window. + * + * The variable can be set to the following values: + * + * - "0": SDL will not send an SDL_EVENT_QUIT event when the last window is + * requesting to close. Note that in this case, there are still other + * legitimate reasons one might get an SDL_EVENT_QUIT event: choosing "Quit" + * from the macOS menu bar, sending a SIGINT (ctrl-c) on Unix, etc. + * - "1": SDL will send a quit event when the last window is requesting to + * close. (default) + * + * If there is at least one active system tray icon, SDL_EVENT_QUIT will + * instead be sent when both the last window will be closed and the last tray + * icon will be destroyed. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_QUIT_ON_LAST_WINDOW_CLOSE = 'SDL_QUIT_ON_LAST_WINDOW_CLOSE'; + +{* + * A variable controlling whether the Direct3D device is initialized for + * thread-safe operations. + * + * The variable can be set to the following values: + * + * - "0": Thread-safety is not enabled. (default) + * - "1": Thread-safety is enabled. + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_RENDER_DIRECT3D_THREADSAFE = 'SDL_RENDER_DIRECT3D_THREADSAFE'; + +{* + * A variable controlling whether to enable Direct3D 11+'s Debug Layer. + * + * This variable does not have any effect on the Direct3D 9 based renderer. + * + * The variable can be set to the following values: + * + * - "0": Disable Debug Layer use. (default) + * - "1": Enable Debug Layer use. + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_RENDER_DIRECT3D11_DEBUG = 'SDL_RENDER_DIRECT3D11_DEBUG'; + +{* + * A variable controlling whether to enable Vulkan Validation Layers. + * + * This variable can be set to the following values: + * + * - "0": Disable Validation Layer use + * - "1": Enable Validation Layer use + * + * By default, SDL does not use Vulkan Validation Layers. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_RENDER_VULKAN_DEBUG = 'SDL_RENDER_VULKAN_DEBUG'; + +{* + * A variable controlling whether to create the GPU device in debug mode. + * + * This variable can be set to the following values: + * + * - "0": Disable debug mode use (default) + * - "1": Enable debug mode use + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_RENDER_GPU_DEBUG = 'SDL_RENDER_GPU_DEBUG'; + +{* + * A variable controlling whether to prefer a low-power GPU on multi-GPU + * systems. + * + * This variable can be set to the following values: + * + * - "0": Prefer high-performance GPU (default) + * - "1": Prefer low-power GPU + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_RENDER_GPU_LOW_POWER = 'SDL_RENDER_GPU_LOW_POWER'; + +{* + * A variable specifying which render driver to use. + * + * If the application doesn't pick a specific renderer to use, this variable + * specifies the name of the preferred renderer. If the preferred renderer + * can't be initialized, creating a renderer will fail. + * + * This variable is case insensitive and can be set to the following values: + * + * - "direct3d" + * - "direct3d11" + * - "direct3d12" + * - "opengl" + * - "opengles2" + * - "opengles" + * - "metal" + * - "vulkan" + * - "gpu" + * - "software" + * + * This hint accepts a comma-separated list of driver names, and each will be + * tried in the order listed when creating a renderer until one succeeds or + * all of them fail. + * + * The default varies by platform, but it's the first one in the list that is + * available on the current platform. + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_RENDER_DRIVER = 'SDL_RENDER_DRIVER'; + +{* + * A variable controlling how the 2D render API renders lines. + * + * The variable can be set to the following values: + * + * - "0": Use the default line drawing method (Bresenham's line algorithm) + * - "1": Use the driver point API using Bresenham's line algorithm (correct, + * draws many points) + * - "2": Use the driver line API (occasionally misses line endpoints based on + * hardware driver quirks + * - "3": Use the driver geometry API (correct, draws thicker diagonal lines) + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_RENDER_LINE_METHOD = 'SDL_RENDER_LINE_METHOD'; + +{* + * A variable controlling whether the Metal render driver select low power + * device over default one. + * + * The variable can be set to the following values: + * + * - "0": Use the preferred OS device. (default) + * - "1": Select a low power device. + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_RENDER_METAL_PREFER_LOW_POWER_DEVICE = 'SDL_RENDER_METAL_PREFER_LOW_POWER_DEVICE'; + +{* + * A variable controlling whether updates to the SDL screen surface should be + * synchronized with the vertical refresh, to avoid tearing. + * + * This hint overrides the application preference when creating a renderer. + * + * The variable can be set to the following values: + * + * - "0": Disable vsync. (default) + * - "1": Enable vsync. + * + * This hint should be set before creating a renderer. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_RENDER_VSYNC = 'SDL_RENDER_VSYNC'; + +{* + * A variable to control whether the return key on the soft keyboard should + * hide the soft keyboard on Android and iOS. + * + * This hint sets the default value of SDL_PROP_TEXTINPUT_MULTILINE_BOOLEAN. + * + * The variable can be set to the following values: + * + * - "0": The return key will be handled as a key event. (default) + * - "1": The return key will hide the keyboard. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_RETURN_KEY_HIDES_IME = 'SDL_RETURN_KEY_HIDES_IME'; + +{* + * A variable containing a list of ROG gamepad capable mice. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + * + * \sa SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED + } + SDL_HINT_ROG_GAMEPAD_MICE = 'SDL_ROG_GAMEPAD_MICE'; + +{* + * A variable containing a list of devices that are not ROG gamepad capable + * mice. + * + * This will override SDL_HINT_ROG_GAMEPAD_MICE and the built in device list. + * + * The format of the string is a comma separated list of USB VID/PID pairs in + * hexadecimal form, e.g. + * + * `0xAAAA/0xBBBB,0xCCCC/0xDDDD` + * + * The variable can also take the form of "@file", in which case the named + * file will be loaded and interpreted as the value of the variable. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_ROG_GAMEPAD_MICE_EXCLUDED = 'SDL_ROG_GAMEPAD_MICE_EXCLUDED'; + +{* + * A variable controlling which Dispmanx layer to use on a Raspberry PI. + * + * Also known as Z-order. The variable can take a negative or positive value. + * The default is 10000. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_RPI_VIDEO_LAYER = 'SDL_RPI_VIDEO_LAYER'; + +{* + * Specify an "activity name" for screensaver inhibition. + * + * Some platforms, notably Linux desktops, list the applications which are + * inhibiting the screensaver or other power-saving features. + * + * This hint lets you specify the "activity name" sent to the OS when + * SDL_DisableScreenSaver() is used (or the screensaver is automatically + * disabled). The contents of this hint are used when the screensaver is + * disabled. You should use a string that describes what your program is doing + * (and, therefore, why the screensaver is disabled). For example, "Playing a + * game" or "Watching a video". + * + * Setting this to "" or leaving it unset will have SDL use a reasonable + * default: "Playing a game" or something similar. + * + * This hint should be set before calling SDL_DisableScreenSaver() + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_SCREENSAVER_INHIBIT_ACTIVITY_NAME = 'SDL_SCREENSAVER_INHIBIT_ACTIVITY_NAME'; + +{* + * A variable controlling whether SDL calls dbus_shutdown() on quit. + * + * This is useful as a debug tool to validate memory leaks, but shouldn't ever + * be set in production applications, as other libraries used by the + * application might use dbus under the hood and this can cause crashes if + * they continue after SDL_Quit(). + * + * The variable can be set to the following values: + * + * - "0": SDL will not call dbus_shutdown() on quit. (default) + * - "1": SDL will call dbus_shutdown() on quit. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_SHUTDOWN_DBUS_ON_QUIT = 'SDL_SHUTDOWN_DBUS_ON_QUIT'; + +{* + * A variable that specifies a backend to use for title storage. + * + * By default, SDL will try all available storage backends in a reasonable + * order until it finds one that can work, but this hint allows the app or + * user to force a specific target, such as "pc" if, say, you are on Steam but + * want to avoid SteamRemoteStorage for title data. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_STORAGE_TITLE_DRIVER = 'SDL_STORAGE_TITLE_DRIVER'; + +{* + * A variable that specifies a backend to use for user storage. + * + * By default, SDL will try all available storage backends in a reasonable + * order until it finds one that can work, but this hint allows the app or + * user to force a specific target, such as "pc" if, say, you are on Steam but + * want to avoid SteamRemoteStorage for user data. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_STORAGE_USER_DRIVER = 'SDL_STORAGE_USER_DRIVER'; + +{* + * Specifies whether SDL_THREAD_PRIORITY_TIME_CRITICAL should be treated as + * realtime. + * + * On some platforms, like Linux, a realtime priority thread may be subject to + * restrictions that require special handling by the application. This hint + * exists to let SDL know that the app is prepared to handle said + * restrictions. + * + * On Linux, SDL will apply the following configuration to any thread that + * becomes realtime: + * + * - The SCHED_RESET_ON_FORK bit will be set on the scheduling policy, + * - An RLIMIT_RTTIME budget will be configured to the rtkit specified limit. + * - Exceeding this limit will result in the kernel sending SIGKILL to the + * app, refer to the man pages for more information. + * + * The variable can be set to the following values: + * + * - "0": default platform specific behaviour + * - "1": Force SDL_THREAD_PRIORITY_TIME_CRITICAL to a realtime scheduling + * policy + * + * This hint should be set before calling SDL_SetCurrentThreadPriority() + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_THREAD_FORCE_REALTIME_TIME_CRITICAL = 'SDL_THREAD_FORCE_REALTIME_TIME_CRITICAL'; + +{* + * A string specifying additional information to use with + * SDL_SetCurrentThreadPriority. + * + * By default SDL_SetCurrentThreadPriority will make appropriate system + * changes in order to apply a thread priority. For example on systems using + * pthreads the scheduler policy is changed automatically to a policy that + * works well with a given priority. Code which has specific requirements can + * override SDL's default behavior with this hint. + * + * pthread hint values are "current", "other", "fifo" and "rr". Currently no + * other platform hint values are defined but may be in the future. + * + * On Linux, the kernel may send SIGKILL to realtime tasks which exceed the + * distro configured execution budget for rtkit. This budget can be queried + * through RLIMIT_RTTIME after calling SDL_SetCurrentThreadPriority(). + * + * This hint should be set before calling SDL_SetCurrentThreadPriority() + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_THREAD_PRIORITY_POLICY = 'SDL_THREAD_PRIORITY_POLICY'; + +{* + * A variable that controls the timer resolution, in milliseconds. + * + * The higher resolution the timer, the more frequently the CPU services timer + * interrupts, and the more precise delays are, but this takes up power and + * CPU time. This hint is only used on Windows. + * + * See this blog post for more information: + * http://randomascii.wordpress.com/2013/07/08/windows-timer-resolution-megawatts-wasted/ + * + * The default value is "1". + * + * If this variable is set to "0", the system timer resolution is not set. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_TIMER_RESOLUTION = 'SDL_TIMER_RESOLUTION'; + +{* + * A variable controlling whether touch events should generate synthetic mouse + * events. + * + * The variable can be set to the following values: + * + * - "0": Touch events will not generate mouse events. + * - "1": Touch events will generate mouse events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_TOUCH_MOUSE_EVENTS = 'SDL_TOUCH_MOUSE_EVENTS'; + +{* + * A variable controlling whether trackpads should be treated as touch + * devices. + * + * On macOS (and possibly other platforms in the future), SDL will report + * touches on a trackpad as mouse input, which is generally what users expect + * from this device; however, these are often actually full multitouch-capable + * touch devices, so it might be preferable to some apps to treat them as + * such. + * + * The variable can be set to the following values: + * + * - "0": Trackpad will send mouse events. (default) + * - "1": Trackpad will send touch events. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_TRACKPAD_IS_TOUCH_ONLY = 'SDL_TRACKPAD_IS_TOUCH_ONLY'; + +{* + * A variable controlling whether the Android / tvOS remotes should be listed + * as joystick devices, instead of sending keyboard events. + * + * The variable can be set to the following values: + * + * - "0": Remotes send enter/escape/arrow key events. + * - "1": Remotes are available as 2 axis, 2 button joysticks. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_TV_REMOTE_AS_JOYSTICK = 'SDL_TV_REMOTE_AS_JOYSTICK'; + +{* + * A variable controlling whether the screensaver is enabled. + * + * The variable can be set to the following values: + * + * - "0": Disable screensaver. (default) + * - "1": Enable screensaver. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_ALLOW_SCREENSAVER = 'SDL_VIDEO_ALLOW_SCREENSAVER'; + +{* + * A comma separated list containing the names of the displays that SDL should + * sort to the front of the display list. + * + * When this hint is set, displays with matching name strings will be + * prioritized in the list of displays, as exposed by calling + * SDL_GetDisplays(), with the first listed becoming the primary display. The + * naming convention can vary depending on the environment, but it is usually + * a connector name (e.g. 'DP-1', 'DP-2', 'HDMI-A-1',etc...). + * + * On Wayland and X11 desktops, the connector names associated with displays + * can typically be found by using the `xrandr` utility. + * + * This hint is currently supported on the following drivers: + * + * - KMSDRM (kmsdrm) + * - Wayland (wayland) + * - X11 (x11) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_DISPLAY_PRIORITY = 'SDL_VIDEO_DISPLAY_PRIORITY'; + +{* + * Tell the video driver that we only want a double buffer. + * + * By default, most lowlevel 2D APIs will use a triple buffer scheme that + * wastes no CPU time on waiting for vsync after issuing a flip, but + * introduces a frame of latency. On the other hand, using a double buffer + * scheme instead is recommended for cases where low latency is an important + * factor because we save a whole frame of latency. + * + * We do so by waiting for vsync immediately after issuing a flip, usually + * just after eglSwapBuffers call in the backend's *_SwapWindow function. + * + * This hint is currently supported on the following drivers: + * + * - Raspberry Pi (raspberrypi) + * - Wayland (wayland) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_DOUBLE_BUFFER = 'SDL_VIDEO_DOUBLE_BUFFER'; + +{* + * A variable that specifies a video backend to use. + * + * By default, SDL will try all available video backends in a reasonable order + * until it finds one that can work, but this hint allows the app or user to + * force a specific target, such as "x11" if, say, you are on Wayland but want + * to try talking to the X server instead. + * + * This hint accepts a comma-separated list of driver names, and each will be + * tried in the order listed during init, until one succeeds or all of them + * fail. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_DRIVER = 'SDL_VIDEO_DRIVER'; + +{* + * A variable controlling whether the dummy video driver saves output frames. + * + * - "0": Video frames are not saved to disk. (default) + * - "1": Video frames are saved to files in the format "SDL_windowX-Y.bmp", + * where X is the window ID, and Y is the frame number. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_DUMMY_SAVE_FRAMES = 'SDL_VIDEO_DUMMY_SAVE_FRAMES'; + +{* + * If eglGetPlatformDisplay fails, fall back to calling eglGetDisplay. + * + * The variable can be set to one of the following values: + * + * - "0": Do not fall back to eglGetDisplay. + * - "1": Fall back to eglGetDisplay if eglGetPlatformDisplay fails. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK = 'SDL_VIDEO_EGL_ALLOW_GETDISPLAY_FALLBACK'; + +{* + * A variable controlling whether the OpenGL context should be created with + * EGL. + * + * The variable can be set to the following values: + * + * - "0": Use platform-specific GL context creation API (GLX, WGL, CGL, etc). + * (default) + * - "1": Use EGL + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_FORCE_EGL = 'SDL_VIDEO_FORCE_EGL'; + +{* + * A variable that specifies the policy for fullscreen Spaces on macOS. + * + * The variable can be set to the following values: + * + * - "0": Disable Spaces support (FULLSCREEN_DESKTOP won't use them and + * SDL_WINDOW_RESIZABLE windows won't offer the "fullscreen" button on their + * titlebars). + * - "1": Enable Spaces support (FULLSCREEN_DESKTOP will use them and + * SDL_WINDOW_RESIZABLE windows will offer the "fullscreen" button on their + * titlebars). (default) + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_MAC_FULLSCREEN_SPACES = 'SDL_VIDEO_MAC_FULLSCREEN_SPACES'; + +{* + * A variable that specifies the menu visibility when a window is fullscreen + * in Spaces on macOS. + * + * The variable can be set to the following values: + * + * - "0": The menu will be hidden when the window is in a fullscreen space, + * and not accessible by moving the mouse to the top of the screen. + * - "1": The menu will be accessible when the window is in a fullscreen + * space. + * - "auto": The menu will be hidden if fullscreen mode was toggled on + * programmatically via `SDL_SetWindowFullscreen()`, and accessible if + * fullscreen was entered via the "fullscreen" button on the window title + * bar. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY = 'SDL_VIDEO_MAC_FULLSCREEN_MENU_VISIBILITY'; + +{* + * A variable controlling whether fullscreen windows are minimized when they + * lose focus. + * + * The variable can be set to the following values: + * + * - "0": Fullscreen windows will not be minimized when they lose focus. + * (default) + * - "1": Fullscreen windows are minimized when they lose focus. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_MINIMIZE_ON_FOCUS_LOSS = 'SDL_VIDEO_MINIMIZE_ON_FOCUS_LOSS'; + +{* + * A variable controlling whether the offscreen video driver saves output + * frames. + * + * This only saves frames that are generated using software rendering, not + * accelerated OpenGL rendering. + * + * - "0": Video frames are not saved to disk. (default) + * - "1": Video frames are saved to files in the format "SDL_windowX-Y.bmp", + * where X is the window ID, and Y is the frame number. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_OFFSCREEN_SAVE_FRAMES = 'SDL_VIDEO_OFFSCREEN_SAVE_FRAMES'; + +{* + * A variable controlling whether all window operations will block until + * complete. + * + * Window systems that run asynchronously may not have the results of window + * operations that resize or move the window applied immediately upon the + * return of the requesting function. Setting this hint will cause such + * operations to block after every call until the pending operation has + * completed. Setting this to '1' is the equivalent of calling + * SDL_SyncWindow() after every function call. + * + * Be aware that amount of time spent blocking while waiting for window + * operations to complete can be quite lengthy, as animations may have to + * complete, which can take upwards of multiple seconds in some cases. + * + * The variable can be set to the following values: + * + * - "0": Window operations are non-blocking. (default) + * - "1": Window operations will block until completed. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_SYNC_WINDOW_OPERATIONS = 'SDL_VIDEO_SYNC_WINDOW_OPERATIONS'; + +{* + * A variable controlling whether the libdecor Wayland backend is allowed to + * be used. + * + * libdecor is used over xdg-shell when xdg-decoration protocol is + * unavailable. + * + * The variable can be set to the following values: + * + * - "0": libdecor use is disabled. + * - "1": libdecor use is enabled. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_WAYLAND_ALLOW_LIBDECOR = 'SDL_VIDEO_WAYLAND_ALLOW_LIBDECOR'; + +{* + * A variable controlling whether video mode emulation is enabled under + * Wayland. + * + * When this hint is set, a standard set of emulated CVT video modes will be + * exposed for use by the application. If it is disabled, the only modes + * exposed will be the logical desktop size and, in the case of a scaled + * desktop, the native display resolution. + * + * The variable can be set to the following values: + * + * - "0": Video mode emulation is disabled. + * - "1": Video mode emulation is enabled. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_WAYLAND_MODE_EMULATION = 'SDL_VIDEO_WAYLAND_MODE_EMULATION'; + +{* + * A variable controlling how modes with a non-native aspect ratio are + * displayed under Wayland. + * + * When this hint is set, the requested scaling will be used when displaying + * fullscreen video modes that don't match the display's native aspect ratio. + * This is contingent on compositor viewport support. + * + * The variable can be set to the following values: + * + * - "aspect" - Video modes will be displayed scaled, in their proper aspect + * ratio, with black bars. + * - "stretch" - Video modes will be scaled to fill the entire display. + * (default) + * - "none" - Video modes will be displayed as 1: 1 with no scaling. + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_WAYLAND_MODE_SCALING = 'SDL_VIDEO_WAYLAND_MODE_SCALING'; + +{* + * A variable controlling whether the libdecor Wayland backend is preferred + * over native decorations. + * + * When this hint is set, libdecor will be used to provide window decorations, + * even if xdg-decoration is available. (Note that, by default, libdecor will + * use xdg-decoration itself if available). + * + * The variable can be set to the following values: + * + * - "0": libdecor is enabled only if server-side decorations are unavailable. + * (default) + * - "1": libdecor is always enabled if available. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_WAYLAND_PREFER_LIBDECOR = 'SDL_VIDEO_WAYLAND_PREFER_LIBDECOR'; + +{* + * A variable forcing non-DPI-aware Wayland windows to output at 1: 1 scaling. + * + * This must be set before initializing the video subsystem. + * + * When this hint is set, Wayland windows that are not flagged as being + * DPI-aware will be output with scaling designed to force 1: 1 pixel mapping. + * + * This is intended to allow legacy applications to be displayed without + * desktop scaling being applied, and has issues with certain display + * configurations, as this forces the window to behave in a way that Wayland + * desktops were not designed to accommodate: + * + * - Rounding errors can result with odd window sizes and/or desktop scales, + * which can cause the window contents to appear slightly blurry. + * - Positioning the window may be imprecise due to unit conversions and + * rounding. + * - The window may be unusably small on scaled desktops. + * - The window may jump in size when moving between displays of different + * scale factors. + * - Displays may appear to overlap when using a multi-monitor setup with + * scaling enabled. + * - Possible loss of cursor precision due to the logical size of the window + * being reduced. + * + * New applications should be designed with proper DPI awareness handling + * instead of enabling this. + * + * The variable can be set to the following values: + * + * - "0": Windows will be scaled normally. + * - "1": Windows will be forced to scale to achieve 1: 1 output. + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_WAYLAND_SCALE_TO_DISPLAY = 'SDL_VIDEO_WAYLAND_SCALE_TO_DISPLAY'; + +{* + * A variable specifying which shader compiler to preload when using the + * Chrome ANGLE binaries. + * + * SDL has EGL and OpenGL ES2 support on Windows via the ANGLE project. It can + * use two different sets of binaries, those compiled by the user from source + * or those provided by the Chrome browser. In the later case, these binaries + * require that SDL loads a DLL providing the shader compiler. + * + * The variable can be set to the following values: + * + * - "d3dcompiler_46.dll" - best for Vista or later. (default) + * - "d3dcompiler_43.dll" - for XP support. + * - "none" - do not load any library, useful if you compiled ANGLE from + * source and included the compiler in your binaries. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_WIN_D3DCOMPILER = 'SDL_VIDEO_WIN_D3DCOMPILER'; + +{* + * A variable controlling whether the X11 _NET_WM_BYPASS_COMPOSITOR hint + * should be used. + * + * The variable can be set to the following values: + * + * - "0": Disable _NET_WM_BYPASS_COMPOSITOR. + * - "1": Enable _NET_WM_BYPASS_COMPOSITOR. (default) + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR = 'SDL_VIDEO_X11_NET_WM_BYPASS_COMPOSITOR'; + +{* + * A variable controlling whether the X11 _NET_WM_PING protocol should be + * supported. + * + * By default SDL will use _NET_WM_PING, but for applications that know they + * will not always be able to respond to ping requests in a timely manner they + * can turn it off to avoid the window manager thinking the app is hung. + * + * The variable can be set to the following values: + * + * - "0": Disable _NET_WM_PING. + * - "1": Enable _NET_WM_PING. (default) + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_X11_NET_WM_PING = 'SDL_VIDEO_X11_NET_WM_PING'; + +{* + * A variable controlling whether SDL uses DirectColor visuals. + * + * The variable can be set to the following values: + * + * - "0": Disable DirectColor visuals. + * - "1": Enable DirectColor visuals. (default) + * + * This hint should be set before initializing the video subsystem. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_X11_NODIRECTCOLOR = 'SDL_VIDEO_X11_NODIRECTCOLOR'; + +{* + * A variable forcing the content scaling factor for X11 displays. + * + * The variable can be set to a floating point value in the range 1.0-10.0f + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_X11_SCALING_FACTOR = 'SDL_VIDEO_X11_SCALING_FACTOR'; + +{* + * A variable forcing the visual ID used for X11 display modes. + * + * This hint should be set before initializing the video subsystem. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_X11_VISUALID = 'SDL_VIDEO_X11_VISUALID'; + +{* + * A variable forcing the visual ID chosen for new X11 windows. + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_X11_WINDOW_VISUALID = 'SDL_VIDEO_X11_WINDOW_VISUALID'; + +{* + * A variable controlling whether the X11 XRandR extension should be used. + * + * The variable can be set to the following values: + * + * - "0": Disable XRandR. + * - "1": Enable XRandR. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VIDEO_X11_XRANDR = 'SDL_VIDEO_X11_XRANDR'; + +{* + * A variable controlling whether touch should be enabled on the back panel of + * the PlayStation Vita. + * + * The variable can be set to the following values: + * + * - "0": Disable touch on the back panel. + * - "1": Enable touch on the back panel. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VITA_ENABLE_BACK_TOUCH = 'SDL_VITA_ENABLE_BACK_TOUCH'; + +{* + * A variable controlling whether touch should be enabled on the front panel + * of the PlayStation Vita. + * + * The variable can be set to the following values: + * + * - "0": Disable touch on the front panel. + * - "1": Enable touch on the front panel. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VITA_ENABLE_FRONT_TOUCH = 'SDL_VITA_ENABLE_FRONT_TOUCH'; + +{* + * A variable controlling the module path on the PlayStation Vita. + * + * This hint defaults to "app0: module" + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VITA_MODULE_PATH = 'SDL_VITA_MODULE_PATH'; + +{* + * A variable controlling whether to perform PVR initialization on the + * PlayStation Vita. + * + * - "0": Skip PVR initialization. + * - "1": Perform the normal PVR initialization. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VITA_PVR_INIT = 'SDL_VITA_PVR_INIT'; + +{* + * A variable overriding the resolution reported on the PlayStation Vita. + * + * The variable can be set to the following values: + * + * - "544": 544p (default) + * - "720": 725p for PSTV + * - "1080": 1088i for PSTV + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VITA_RESOLUTION = 'SDL_VITA_RESOLUTION'; + +{* + * A variable controlling whether OpenGL should be used instead of OpenGL ES + * on the PlayStation Vita. + * + * The variable can be set to the following values: + * + * - "0": Use OpenGL ES. (default) + * - "1": Use OpenGL. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VITA_PVR_OPENGL = 'SDL_VITA_PVR_OPENGL'; + +{* + * A variable controlling which touchpad should generate synthetic mouse + * events. + * + * The variable can be set to the following values: + * + * - "0": Only front touchpad should generate mouse events. (default) + * - "1": Only back touchpad should generate mouse events. + * - "2": Both touchpads should generate mouse events. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VITA_TOUCH_MOUSE_DEVICE = 'SDL_VITA_TOUCH_MOUSE_DEVICE'; + +{* + * A variable overriding the display index used in SDL_Vulkan_CreateSurface() + * + * The display index starts at 0, which is the default. + * + * This hint should be set before calling SDL_Vulkan_CreateSurface() + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VULKAN_DISPLAY = 'SDL_VULKAN_DISPLAY'; + +{* + * Specify the Vulkan library to load. + * + * This hint should be set before creating a Vulkan window or calling + * SDL_Vulkan_LoadLibrary(). + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_VULKAN_LIBRARY = 'SDL_VULKAN_LIBRARY'; + +{* + * A variable controlling how the fact chunk affects the loading of a WAVE + * file. + * + * The fact chunk stores information about the number of samples of a WAVE + * file. The Standards Update from Microsoft notes that this value can be used + * to 'determine the length of the data in seconds'. This is especially useful + * for compressed formats (for which this is a mandatory chunk) if they + * produce multiple sample frames per block and truncating the block is not + * allowed. The fact chunk can exactly specify how many sample frames there + * should be in this case. + * + * Unfortunately, most application seem to ignore the fact chunk and so SDL + * ignores it by default as well. + * + * The variable can be set to the following values: + * + * - "truncate" - Use the number of samples to truncate the wave data if the + * fact chunk is present and valid. + * - "strict" - Like "truncate", but raise an error if the fact chunk is + * invalid, not present for non-PCM formats, or if the data chunk doesn't + * have that many samples. + * - "ignorezero" - Like "truncate", but ignore fact chunk if the number of + * samples is zero. + * - "ignore" - Ignore fact chunk entirely. (default) + * + * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WAVE_FACT_CHUNK = 'SDL_WAVE_FACT_CHUNK'; + +{* + * A variable controlling the maximum number of chunks in a WAVE file. + * + * This sets an upper bound on the number of chunks in a WAVE file to avoid + * wasting time on malformed or corrupt WAVE files. This defaults to "10000". + * + * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WAVE_CHUNK_LIMIT = 'SDL_WAVE_CHUNK_LIMIT'; + +{* + * A variable controlling how the size of the RIFF chunk affects the loading + * of a WAVE file. + * + * The size of the RIFF chunk (which includes all the sub-chunks of the WAVE + * file) is not always reliable. In case the size is wrong, it's possible to + * just ignore it and step through the chunks until a fixed limit is reached. + * + * Note that files that have trailing data unrelated to the WAVE file or + * corrupt files may slow down the loading process without a reliable + * boundary. By default, SDL stops after 10000 chunks to prevent wasting time. + * Use SDL_HINT_WAVE_CHUNK_LIMIT to adjust this value. + * + * The variable can be set to the following values: + * + * - "force" - Always use the RIFF chunk size as a boundary for the chunk + * search. + * - "ignorezero" - Like "force", but a zero size searches up to 4 GiB. + * (default) + * - "ignore" - Ignore the RIFF chunk size and always search up to 4 GiB. + * - "maximum" - Search for chunks until the end of file. (not recommended) + * + * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WAVE_RIFF_CHUNK_SIZE = 'SDL_WAVE_RIFF_CHUNK_SIZE'; + +{* + * A variable controlling how a truncated WAVE file is handled. + * + * A WAVE file is considered truncated if any of the chunks are incomplete or + * the data chunk size is not a multiple of the block size. By default, SDL + * decodes until the first incomplete block, as most applications seem to do. + * + * The variable can be set to the following values: + * + * - "verystrict" - Raise an error if the file is truncated. + * - "strict" - Like "verystrict", but the size of the RIFF chunk is ignored. + * - "dropframe" - Decode until the first incomplete sample frame. + * - "dropblock" - Decode until the first incomplete block. (default) + * + * This hint should be set before calling SDL_LoadWAV() or SDL_LoadWAV_IO() + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WAVE_TRUNCATION = 'SDL_WAVE_TRUNCATION'; + +{* + * A variable controlling whether the window is activated when the + * SDL_RaiseWindow function is called. + * + * The variable can be set to the following values: + * + * - "0": The window is not activated when the SDL_RaiseWindow function is + * called. + * - "1": The window is activated when the SDL_RaiseWindow function is called. + * (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WINDOW_ACTIVATE_WHEN_RAISED = 'SDL_WINDOW_ACTIVATE_WHEN_RAISED'; + +{* + * A variable controlling whether the window is activated when the + * SDL_ShowWindow function is called. + * + * The variable can be set to the following values: + * + * - "0": The window is not activated when the SDL_ShowWindow function is + * called. + * - "1": The window is activated when the SDL_ShowWindow function is called. + * (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WINDOW_ACTIVATE_WHEN_SHOWN = 'SDL_WINDOW_ACTIVATE_WHEN_SHOWN'; + +{* + * If set to "0" then never set the top-most flag on an SDL Window even if the + * application requests it. + * + * This is a debugging aid for developers and not expected to be used by end + * users. + * + * The variable can be set to the following values: + * + * - "0": don't allow topmost + * - "1": allow topmost (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WINDOW_ALLOW_TOPMOST = 'SDL_WINDOW_ALLOW_TOPMOST'; + +{* + * A variable controlling whether the window frame and title bar are + * interactive when the cursor is hidden. + * + * The variable can be set to the following values: + * + * - "0": The window frame is not interactive when the cursor is hidden (no + * move, resize, etc). + * - "1": The window frame is interactive when the cursor is hidden. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN = 'SDL_WINDOW_FRAME_USABLE_WHILE_CURSOR_HIDDEN'; + +{* + * A variable controlling whether SDL generates window-close events for Alt+F4 + * on Windows. + * + * The variable can be set to the following values: + * + * - "0": SDL will only do normal key handling for Alt+F4. + * - "1": SDL will generate a window-close event when it sees Alt+F4. + * (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WINDOWS_CLOSE_ON_ALT_F4 = 'SDL_WINDOWS_CLOSE_ON_ALT_F4'; + +{* + * A variable controlling whether menus can be opened with their keyboard + * shortcut (Alt+mnemonic). + * + * If the mnemonics are enabled, then menus can be opened by pressing the Alt + * key and the corresponding mnemonic (for example, Alt+F opens the File + * menu). However, in case an invalid mnemonic is pressed, Windows makes an + * audible beep to convey that nothing happened. This is true even if the + * window has no menu at all! + * + * Because most SDL applications don't have menus, and some want to use the + * Alt key for other purposes, SDL disables mnemonics (and the beeping) by + * default. + * + * Note: This also affects keyboard events: with mnemonics enabled, when a + * menu is opened from the keyboard, you will not receive a KEYUP event for + * the mnemonic key, and *might* not receive one for Alt. + * + * The variable can be set to the following values: + * + * - "0": Alt+mnemonic does nothing, no beeping. (default) + * - "1": Alt+mnemonic opens menus, invalid mnemonics produce a beep. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WINDOWS_ENABLE_MENU_MNEMONICS = 'SDL_WINDOWS_ENABLE_MENU_MNEMONICS'; + +{* + * A variable controlling whether the windows message loop is processed by + * SDL. + * + * The variable can be set to the following values: + * + * - "0": The window message loop is not run. + * - "1": The window message loop is processed in SDL_PumpEvents(). (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WINDOWS_ENABLE_MESSAGELOOP = 'SDL_WINDOWS_ENABLE_MESSAGELOOP'; + +{* + * A variable controlling whether GameInput is used for raw keyboard and mouse + * on Windows. + * + * The variable can be set to the following values: + * + * - "0": GameInput is not used for raw keyboard and mouse events. + * - "1": GameInput is used for raw keyboard and mouse events, if available. + * (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WINDOWS_GAMEINPUT = 'SDL_WINDOWS_GAMEINPUT'; + +{* + * A variable controlling whether raw keyboard events are used on Windows. + * + * The variable can be set to the following values: + * + * - "0": The Windows message loop is used for keyboard events. (default) + * - "1": Low latency raw keyboard events are used. + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WINDOWS_RAW_KEYBOARD = 'SDL_WINDOWS_RAW_KEYBOARD'; + +{* + * A variable controlling whether SDL uses Kernel Semaphores on Windows. + * + * Kernel Semaphores are inter-process and require a context switch on every + * interaction. On Windows 8 and newer, the WaitOnAddress API is available. + * Using that and atomics to implement semaphores increases performance. SDL + * will fall back to Kernel Objects on older OS versions or if forced to by + * this hint. + * + * The variable can be set to the following values: + * + * - "0": Use Atomics and WaitOnAddress API when available, otherwise fall + * back to Kernel Objects. (default) + * - "1": Force the use of Kernel Objects in all cases. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WINDOWS_FORCE_SEMAPHORE_KERNEL = 'SDL_WINDOWS_FORCE_SEMAPHORE_KERNEL'; + +{* + * A variable to specify custom icon resource id from RC file on Windows + * platform. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WINDOWS_INTRESOURCE_ICON = 'SDL_WINDOWS_INTRESOURCE_ICON'; + +{* + * A variable to specify custom icon resource id from RC file on Windows + * platform. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL = 'SDL_WINDOWS_INTRESOURCE_ICON_SMALL'; + +{* + * A variable controlling whether SDL uses the D3D9Ex API introduced in + * Windows Vista, instead of normal D3D9. + * + * Direct3D 9Ex contains changes to state management that can eliminate device + * loss errors during scenarios like Alt+Tab or UAC prompts. D3D9Ex may + * require some changes to your application to cope with the new behavior, so + * this is disabled by default. + * + * For more information on Direct3D 9Ex, see: + * + * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/graphics-apis-in-windows-vista#direct3d-9ex + * - https://docs.microsoft.com/en-us/windows/win32/direct3darticles/direct3d-9ex-improvements + * + * The variable can be set to the following values: + * + * - "0": Use the original Direct3D 9 API. (default) + * - "1": Use the Direct3D 9Ex API on Vista and later (and fall back if D3D9Ex + * is unavailable) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WINDOWS_USE_D3D9EX = 'SDL_WINDOWS_USE_D3D9EX'; + +{* + * A variable controlling whether SDL will clear the window contents when the + * WM_ERASEBKGND message is received. + * + * The variable can be set to the following values: + * + * - "0"/"never": Never clear the window. + * - "1"/"initial": Clear the window when the first WM_ERASEBKGND event fires. + * (default) + * - "2"/"always": Clear the window on every WM_ERASEBKGND event. + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_WINDOWS_ERASE_BACKGROUND_MODE = 'SDL_WINDOWS_ERASE_BACKGROUND_MODE'; + +{* + * A variable controlling whether X11 windows are marked as override-redirect. + * + * If set, this _might_ increase framerate at the expense of the desktop not + * working as expected. Override-redirect windows aren't noticed by the window + * manager at all. + * + * You should probably only use this for fullscreen windows, and you probably + * shouldn't even use it for that. But it's here if you want to try! + * + * The variable can be set to the following values: + * + * - "0": Do not mark the window as override-redirect. (default) + * - "1": Mark the window as override-redirect. + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_X11_FORCE_OVERRIDE_REDIRECT = 'SDL_X11_FORCE_OVERRIDE_REDIRECT'; + +{* + * A variable specifying the type of an X11 window. + * + * During SDL_CreateWindow, SDL uses the _NET_WM_WINDOW_TYPE X11 property to + * report to the window manager the type of window it wants to create. This + * might be set to various things if SDL_WINDOW_TOOLTIP or + * SDL_WINDOW_POPUP_MENU, etc, were specified. For "normal" windows that + * haven't set a specific type, this hint can be used to specify a custom + * type. For example, a dock window might set this to + * "_NET_WM_WINDOW_TYPE_DOCK". + * + * This hint should be set before creating a window. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_X11_WINDOW_TYPE = 'SDL_X11_WINDOW_TYPE'; + +{* + * Specify the XCB library to load for the X11 driver. + * + * The default is platform-specific, often "libX11-xcb.so.1". + * + * This hint should be set before initializing the video subsystem. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_X11_XCB_LIBRARY = 'SDL_X11_XCB_LIBRARY'; + +{* + * A variable controlling whether XInput should be used for controller + * handling. + * + * The variable can be set to the following values: + * + * - "0": XInput is not enabled. + * - "1": XInput is enabled. (default) + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_XINPUT_ENABLED = 'SDL_XINPUT_ENABLED'; + +{* + * A variable controlling response to SDL_assert failures. + * + * The variable can be set to the following case-sensitive values: + * + * - "abort": Program terminates immediately. + * - "break": Program triggers a debugger breakpoint. + * - "retry": Program reruns the SDL_assert's test again. + * - "ignore": Program continues on, ignoring this assertion failure this + * time. + * - "always_ignore": Program continues on, ignoring this assertion failure + * for the rest of the run. + * + * Note that SDL_SetAssertionHandler offers a programmatic means to deal with + * assertion failures through a callback, and this hint is largely intended to + * be used via environment variables by end users and automated tools. + * + * This hint should be set before an assertion failure is triggered and can be + * changed at any time. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_ASSERT = 'SDL_ASSERT'; + +{* + * A variable controlling whether pen events should generate synthetic mouse + * events. + * + * The variable can be set to the following values: + * + * - "0": Pen events will not generate mouse events. + * - "1": Pen events will generate mouse events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_PEN_MOUSE_EVENTS = 'SDL_PEN_MOUSE_EVENTS'; + +{* + * A variable controlling whether pen events should generate synthetic touch + * events. + * + * The variable can be set to the following values: + * + * - "0": Pen events will not generate touch events. + * - "1": Pen events will generate touch events. (default) + * + * This hint can be set anytime. + * + * \since This hint is available since SDL 3.2.0. + } + SDL_HINT_PEN_TOUCH_EVENTS = 'SDL_PEN_TOUCH_EVENTS'; + +{* + * An enumeration of hint priorities. + * + * \since This enum is available since SDL 3.2.0. + } +type + PPSDL_HintPriority = ^PSDL_HintPriority; + PSDL_HintPriority = ^TSDL_HintPriority; + TSDL_HintPriority = type Integer; +const + SDL_HINT_DEFAULT = TSDL_HintPriority(0); + SDL_HINT_NORMAL = TSDL_HintPriority(1); + SDL_HINT_OVERRIDE = TSDL_HintPriority(2); + +{* + * Set a hint with a specific priority. + * + * The priority controls the behavior when setting a hint that already has a + * value. Hints will replace existing hints of their priority and lower. + * Environment variables are considered to have override priority. + * + * \param name the hint to set. + * \param value the value of the hint variable. + * \param priority the SDL_HintPriority level for the hint. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetHint + * \sa SDL_ResetHint + * \sa SDL_SetHint + } +function SDL_SetHintWithPriority(name: PAnsiChar; value: PAnsiChar; priority: TSDL_HintPriority): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetHintWithPriority' {$ENDIF} {$ENDIF}; + +{* + * Set a hint with normal priority. + * + * Hints will not be set if there is an existing override hint or environment + * variable that takes precedence. You can use SDL_SetHintWithPriority() to + * set the hint with override priority instead. + * + * \param name the hint to set. + * \param value the value of the hint variable. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetHint + * \sa SDL_ResetHint + * \sa SDL_SetHintWithPriority + } +function SDL_SetHint(name: PAnsiChar; value: PAnsiChar): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetHint' {$ENDIF} {$ENDIF}; + +{* + * Reset a hint to the default value. + * + * This will reset a hint to the value of the environment variable, or nil if + * the environment isn't set. Callbacks will be called normally with this + * change. + * + * \param name the hint to set. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetHint + * \sa SDL_ResetHints + } +function SDL_ResetHint(name: PAnsiChar): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ResetHint' {$ENDIF} {$ENDIF}; + +{* + * Reset all hints to the default values. + * + * This will reset all hints to the value of the associated environment + * variable, or nil if the environment isn't set. Callbacks will be called + * normally with this change. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ResetHint + } +procedure SDL_ResetHints; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ResetHints' {$ENDIF} {$ENDIF}; + +{* + * Get the value of a hint. + * + * \param name the hint to query. + * \returns the string value of a hint or nil if the hint isn't set. + * + * \threadsafety It is safe to call this function from any thread, however the + * return value only remains valid until the hint is changed; if + * another thread might do so, the app should supply locks + * and/or make a copy of the string. Note that using a hint + * callback instead is always thread-safe, as SDL holds a lock + * on the thread subsystem during the callback. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetHint + * \sa SDL_SetHintWithPriority + } +function SDL_GetHint(name: PAnsiChar): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetHint' {$ENDIF} {$ENDIF}; + +{* + * Get the boolean value of a hint variable. + * + * \param name the name of the hint to get the boolean value from. + * \param default_value the value to return if the hint does not exist. + * \returns the boolean value of a hint or the provided default value if the + * hint does not exist. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetHint + * \sa SDL_SetHint + } +function SDL_GetHincboolean(name: PAnsiChar; default_value: cbool): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetHincboolean' {$ENDIF} {$ENDIF}; + +{* + * A callback used to send notifications of hint value changes. + * + * This is called an initial time during SDL_AddHintCallback with the hint's + * current value, and then again each time the hint's value changes. + * + * \param userdata what was passed as `userdata` to SDL_AddHintCallback(). + * \param name what was passed as `name` to SDL_AddHintCallback(). + * \param oldValue the previous hint value. + * \param newValue the new value hint is to be set to. + * + * \threadsafety This callback is fired from whatever thread is setting a new + * hint value. SDL holds a lock on the hint subsystem when + * calling this callback. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_AddHintCallback + } +type + TSDL_HintCallback = procedure(userdata: Pointer; name: PAnsiChar; oldValue: PAnsiChar; newValue: PAnsiChar); cdecl; + +{* + * Add a function to watch a particular hint. + * + * The callback function is called _during_ this function, to provide it an + * initial value, and again each time the hint's value changes. + * + * \param name the hint to watch. + * \param callback An SDL_HintCallback function that will be called when the + * hint value changes. + * \param userdata a Pointer to pass to the callback function. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RemoveHintCallback + } +function SDL_AddHintCallback(name: PAnsiChar; callback: TSDL_HintCallback; userdata: Pointer): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_AddHintCallback' {$ENDIF} {$ENDIF}; + +{* + * Remove a function watching a particular hint. + * + * \param name the hint being watched. + * \param callback an SDL_HintCallback function that will be called when the + * hint value changes. + * \param userdata a Pointer being passed to the callback function. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_AddHintCallback + } +procedure SDL_RemoveHintCallback(name: PAnsiChar; callback: TSDL_HintCallback; userdata: Pointer); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RemoveHintCallback' {$ENDIF} {$ENDIF}; + From 0b476b87ed728f0aa23eee388fac129dbd11b3a3 Mon Sep 17 00:00:00 2001 From: Matthias Date: Thu, 6 Feb 2025 19:33:22 +0100 Subject: [PATCH 09/18] Add SDL_loadso.inc --- units/SDL3.pas | 2 + units/SDL_loadso.inc | 116 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 units/SDL_loadso.inc diff --git a/units/SDL3.pas b/units/SDL3.pas index f214d75..e5bd097 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -82,6 +82,7 @@ interface {$I SDL_guid.inc} // 3.1.6-prev {$I SDL_hints.inc} // 3.2.0 {$I SDL_stdinc.inc} // 3.1.6-prev (unfinished) +{$I SDL_loadso.inc} // 3.2.0 {$I SDL_rect.inc} // 3.1.6-prev {$I SDL_properties.inc} // 3.1.6-prev {$I SDL_pixels.inc} // 3.1.6-prev @@ -117,6 +118,7 @@ interface {$I SDL_hidapi.inc} // 3.2.0 + implementation { Macros from SDL_version.h } diff --git a/units/SDL_loadso.inc b/units/SDL_loadso.inc new file mode 100644 index 0000000..289c200 --- /dev/null +++ b/units/SDL_loadso.inc @@ -0,0 +1,116 @@ +{ + This file is part of: + + SDL3 for Pascal + (https://github.com/PascalGameDevelopment/SDL3-for-Pascal) + SPDX-License-Identifier: Zlib +} + +{* + * # CategorySharedObject + * + * System-dependent library loading routines. + * + * Shared objects are code that is programmatically loadable at runtime. + * Windows calls these "DLLs", Linux calls them "shared libraries", etc. + * + * To use them, build such a library, then call SDL_LoadObject() on it. Once + * loaded, you can use SDL_LoadFunction() on that object to find the address + * of its exported symbols. When done with the object, call SDL_UnloadObject() + * to dispose of it. + * + * Some things to keep in mind: + * + * - These functions only work on C function names. Other languages may have + * name mangling and intrinsic language support that varies from compiler to + * compiler. + * - Make sure you declare your function pointers with the same calling + * convention as the actual library function. Your code will crash + * mysteriously if you do not do this. + * - Avoid namespace collisions. If you load a symbol from the library, it is + * not defined whether or not it goes into the global symbol namespace for + * the application. If it does and it conflicts with symbols in your code or + * other shared libraries, you will not get the results you expect.:) + * - Once a library is unloaded, all pointers into it obtained through + * SDL_LoadFunction() become invalid, even if the library is later reloaded. + * Don't unload a library if you plan to use these pointers in the future. + * Notably: beware of giving one of these pointers to atexit(), since it may + * call that Pointer after the library unloads. + } + +{* + * An opaque datatype that represents a loaded shared object. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_LoadObject + * \sa SDL_LoadFunction + * \sa SDL_UnloadObject + } +type + PPSDL_SharedObject = ^PSDL_SharedObject; + PSDL_SharedObject = type Pointer; + +{* + * Dynamically load a shared object. + * + * \param sofile a system-dependent name of the object file. + * \returns an opaque Pointer to the object handle or nil on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadFunction + * \sa SDL_UnloadObject + } +function SDL_LoadObject(sofile: PAnsiChar): PSDL_SharedObject; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LoadObject' {$ENDIF} {$ENDIF}; + +{* + * Look up the address of the named function in a shared object. + * + * This function Pointer is no longer valid after calling SDL_UnloadObject(). + * + * This function can only look up C function names. Other languages may have + * name mangling and intrinsic language support that varies from compiler to + * compiler. + * + * Make sure you declare your function pointers with the same calling + * convention as the actual library function. Your code will crash + * mysteriously if you do not do this. + * + * If the requested function doesn't exist, nil is returned. + * + * \param handle a valid shared object handle returned by SDL_LoadObject(). + * \param name the name of the function to look up. + * \returns a Pointer to the function or nil on failure; call SDL_GetError() + * for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadObject + } +function SDL_LoadFunction(handle: PSDL_SharedObject; name: PAnsiChar): TSDL_FunctionPointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_LoadFunction' {$ENDIF} {$ENDIF}; + +{* + * Unload a shared object from memory. + * + * Note that any pointers from this object looked up through + * SDL_LoadFunction() will no longer be valid. + * + * \param handle a valid shared object handle returned by SDL_LoadObject(). + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_LoadObject + } +procedure SDL_UnloadObject(handle: PSDL_SharedObject); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_UnloadObject' {$ENDIF} {$ENDIF}; + From 1179a65f44ce4ac75e1381850e3c0b150c374f75 Mon Sep 17 00:00:00 2001 From: Matthias Date: Thu, 6 Feb 2025 19:37:16 +0100 Subject: [PATCH 10/18] Add SDL_locale.inc --- units/SDL3.pas | 1 + units/SDL_locale.inc | 84 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 units/SDL_locale.inc diff --git a/units/SDL3.pas b/units/SDL3.pas index e5bd097..b770531 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -79,6 +79,7 @@ interface {$I SDL_log.inc} // 3.1.6-prev {$I SDL_version.inc} // 3.1.6-prev {$I SDL_revision.inc} // 3.1.6-prev +{$I SDL_locale.inc} // 3.2.0 {$I SDL_guid.inc} // 3.1.6-prev {$I SDL_hints.inc} // 3.2.0 {$I SDL_stdinc.inc} // 3.1.6-prev (unfinished) diff --git a/units/SDL_locale.inc b/units/SDL_locale.inc new file mode 100644 index 0000000..eea3cea --- /dev/null +++ b/units/SDL_locale.inc @@ -0,0 +1,84 @@ +{ + This file is part of: + + SDL3 for Pascal + (https://github.com/PascalGameDevelopment/SDL3-for-Pascal) + SPDX-License-Identifier: Zlib +} + +{* + * # CategoryLocale + * + * SDL locale services. + * + * This provides a way to get a list of preferred locales (language plus + * country) for the user. There is exactly one function: + * SDL_GetPreferredLocales(), which handles all the heavy lifting, and offers + * documentation on all the strange ways humans might have configured their + * language settings. + } + +{* + * A struct to provide locale data. + * + * Locale data is split into a spoken language, like English, and an optional + * country, like Canada. The language will be in ISO-639 format (so English + * would be "en"), and the country, if not nil, will be an ISO-3166 country + * code (so Canada would be "CA"). + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetPreferredLocales + } +type + PPSDL_Locale = ^PSDL_Locale; + PSDL_Locale = ^TSDL_Locale; + TSDL_Locale = record + language: PAnsiChar; {*< A language name, like "en" for English. } + country: PAnsiChar; {*< A country, like "US" for America. Can be nil. } + end; + +{* + * Report the user's preferred locale. + * + * Returned language strings are in the format xx, where 'xx' is an ISO-639 + * language specifier (such as "en" for English, "de" for German, etc). + * Country strings are in the format YY, where "YY" is an ISO-3166 country + * code (such as "US" for the United States, "CA" for Canada, etc). Country + * might be nil if there's no specific guidance on them (so you might get + * "en", "US" for American English, but "en", nil means "English + * language, generically"). Language strings are never nil, except to + * terminate the array. + * + * Please note that not all of these strings are 2 characters; some are three + * or more. + * + * The returned list of locales are in the order of the user's preference. For + * example, a German citizen that is fluent in US English and knows enough + * Japanese to navigate around Tokyo might have a list like: "de", "en_US", + * "jp", nil . Someone from England might prefer British English (where + * "color" is spelled "colour", etc), but will settle for anything like it: + * "en_GB", "en", nil . + * + * This function returns nil on error, including when the platform does not + * supply this information at all. + * + * This might be a "slow" call that has to query the operating system. It's + * best to ask for this once and save the results. However, this list can + * change, usually because the user has changed a system preference outside of + * your program; SDL will send an SDL_EVENT_LOCALE_CHANGED event in this case, + * if possible, and you can call this function again to get an updated copy of + * preferred locales. + * + * \param count a Pointer filled in with the number of locales returned, may + * be nil. + * \returns a nil terminated array of locale pointers, or nil on failure; + * call SDL_GetError() for more information. This is a single + * allocation that should be freed with SDL_free() when it is no + * longer needed. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetPreferredLocales(count: pcint):PPSDL_Locale; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetPreferredLocales' {$ENDIF} {$ENDIF}; + From 149ef14b8f938cbb2bbe9cac70308a5dc4cfd24e Mon Sep 17 00:00:00 2001 From: Matthias Date: Thu, 6 Feb 2025 19:47:07 +0100 Subject: [PATCH 11/18] Add SDL_messagebox.inc --- units/SDL3.pas | 1 + units/SDL_messagebox.inc | 212 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 213 insertions(+) create mode 100644 units/SDL_messagebox.inc diff --git a/units/SDL3.pas b/units/SDL3.pas index b770531..48d0ef4 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -113,6 +113,7 @@ interface {$I SDL_clipboard.inc} // 3.2.0 {$I SDL_cpuinfo.inc} // 3.2.0 {$I SDL_dialog.inc} // 3.2.0 +{$I SDL_messagebox.inc} // 3.2.0 {$I SDL_time.inc} // 3.2.0 {$I SDL_filesystem.inc} // 3.2.0 {$I SDL_atomic.inc} // 3.2.0 diff --git a/units/SDL_messagebox.inc b/units/SDL_messagebox.inc new file mode 100644 index 0000000..134dd49 --- /dev/null +++ b/units/SDL_messagebox.inc @@ -0,0 +1,212 @@ +{ + This file is part of: + + SDL3 for Pascal + (https://github.com/PascalGameDevelopment/SDL3-for-Pascal) + SPDX-License-Identifier: Zlib +} + +{* + * # CategoryMessagebox + * + * SDL offers a simple message box API, which is useful for simple alerts, + * such as informing the user when something fatal happens at startup without + * the need to build a UI for it (or informing the user _before_ your UI is + * ready). + * + * These message boxes are native system dialogs where possible. + * + * There is both a customizable function (SDL_ShowMessageBox()) that offers + * lots of options for what to display and reports on what choice the user + * made, and also a much-simplified version (SDL_ShowSimpleMessageBox()), + * merely takes a text message and title, and waits until the user presses a + * single "OK" UI button. Often, this is all that is necessary. + } + +{* + * Message box flags. + * + * If supported will display warning icon, etc. + * + * \since This datatype is available since SDL 3.2.0. + } +type + PPSDL_MessageBoxFlags = ^PSDL_MessageBoxFlags; + PSDL_MessageBoxFlags = ^TSDL_MessageBoxFlags; + TSDL_MessageBoxFlags = type cuint32; +const + SDL_MESSAGEBOX_ERROR = TSDL_MessageBoxFlags($00000010); {*< error dialog } + SDL_MESSAGEBOX_WARNING = TSDL_MessageBoxFlags($00000020); {*< warning dialog } + SDL_MESSAGEBOX_INFORMATION = TSDL_MessageBoxFlags($00000040); {*< informational dialog } + SDL_MESSAGEBOX_BUTTONS_LEFT_TO_RIGHT = TSDL_MessageBoxFlags($00000080); {*< buttons placed left to right } + SDL_MESSAGEBOX_BUTTONS_RIGHT_TO_LEFT = TSDL_MessageBoxFlags($00000100); {*< buttons placed right to left } + +{* + * SDL_MessageBoxButtonData flags. + * + * \since This datatype is available since SDL 3.2.0. + } +type + PPSDL_MessageBoxButtonFlags = ^PSDL_MessageBoxButtonFlags; + PSDL_MessageBoxButtonFlags = ^TSDL_MessageBoxButtonFlags; + TSDL_MessageBoxButtonFlags = type cuint32; +const + SDL_MESSAGEBOX_BUTTON_RETURNKEY_DEFAULT = TSDL_MessageBoxButtonFlags($00000001); {*< Marks the default button when return is hit } + SDL_MESSAGEBOX_BUTTON_ESCAPEKEY_DEFAULT = TSDL_MessageBoxButtonFlags($00000002); {*< Marks the default button when escape is hit } + +{* + * Individual button data. + * + * \since This struct is available since SDL 3.2.0. + } +type + PPSDL_MessageBoxButtonData = ^PSDL_MessageBoxButtonData; + PSDL_MessageBoxButtonData = ^TSDL_MessageBoxButtonData; + TSDL_MessageBoxButtonData = record + flags: TSDL_MessageBoxButtonFlags; + buttonID: cint; {*< User defined button id (value returned via SDL_ShowMessageBox) } + text: PAnsiChar; {*< The UTF-8 button text } + end; + +{* + * RGB value used in a message box color scheme + * + * \since This struct is available since SDL 3.2.0. + } +type + PPSDL_MessageBoxColor = ^PSDL_MessageBoxColor; + PSDL_MessageBoxColor = ^TSDL_MessageBoxColor; + TSDL_MessageBoxColor = record + r: cuint8; + g: cuint8; + b: cuint8; + end; + +{* + * An enumeration of indices inside the colors array of + * SDL_MessageBoxColorScheme. + } +type + PPSDL_MessageBoxColorType = ^PSDL_MessageBoxColorType; + PSDL_MessageBoxColorType = ^TSDL_MessageBoxColorType; + TSDL_MessageBoxColorType = type Integer; +const + SDL_MESSAGEBOX_COLOR_BACKGROUND = TSDL_MessageBoxColorType(0); + SDL_MESSAGEBOX_COLOR_TEXT = TSDL_MessageBoxColorType(1); + SDL_MESSAGEBOX_COLOR_BUTTON_BORDER = TSDL_MessageBoxColorType(2); + SDL_MESSAGEBOX_COLOR_BUTTON_BACKGROUND = TSDL_MessageBoxColorType(3); + SDL_MESSAGEBOX_COLOR_BUTTON_SELECTED = TSDL_MessageBoxColorType(4); + SDL_MESSAGEBOX_COLOR_COUNT = TSDL_MessageBoxColorType(5); {*< Size of the colors array of SDL_MessageBoxColorScheme. } + +{* + * A set of colors to use for message box dialogs + * + * \since This struct is available since SDL 3.2.0. + } +type + PPSDL_MessageBoxColorScheme = ^PSDL_MessageBoxColorScheme; + PSDL_MessageBoxColorScheme = ^TSDL_MessageBoxColorScheme; + TSDL_MessageBoxColorScheme = record + colors: array[0..SDL_MESSAGEBOX_COLOR_COUNT-1] of TSDL_MessageBoxColor; + end; + +{* + * MessageBox structure containing title, text, window, etc. + * + * \since This struct is available since SDL 3.2.0. + } +type + PPSDL_MessageBoxData = ^PSDL_MessageBoxData; + PSDL_MessageBoxData = ^TSDL_MessageBoxData; + TSDL_MessageBoxData = record + flags: TSDL_MessageBoxFlags; + window: PSDL_Window; {*< Parent window, can be nil } + title: PAnsiChar; {*< UTF-8 title } + message: PAnsiChar; {*< UTF-8 message text } + + numbuttons: cint; + buttons: PSDL_MessageBoxButtonData; + + colorScheme: PSDL_MessageBoxColorScheme; {*< SDL_MessageBoxColorScheme, can be nil to use system settings } + end; + +{* + * Create a modal message box. + * + * If your needs aren't complex, it might be easier to use + * SDL_ShowSimpleMessageBox. + * + * This function should be called on the thread that created the parent + * window, or on the main thread if the messagebox has no parent. It will + * block execution of that thread until the user clicks a button or closes the + * messagebox. + * + * This function may be called at any time, even before SDL_Init(). This makes + * it useful for reporting errors like a failure to create a renderer or + * OpenGL context. + * + * On X11, SDL rolls its own dialog box with X11 primitives instead of a + * formal toolkit like GTK+ or Qt. + * + * Note that if SDL_Init() would fail because there isn't any available video + * target, this function is likely to fail for the same reasons. If this is a + * concern, check the return value from this function and fall back to writing + * to stderr if you can. + * + * \param messageboxdata the SDL_MessageBoxData structure with title, text and + * other options. + * \param buttonid the Pointer to which user id of hit button should be + * copied. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ShowSimpleMessageBox + } +function SDL_ShowMessageBox(messageboxdata: PSDL_MessageBoxData; buttonid: pcint): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ShowMessageBox' {$ENDIF} {$ENDIF}; + +{* + * Display a simple modal message box. + * + * If your needs aren't complex, this function is preferred over + * SDL_ShowMessageBox. + * + * `flags` may be any of the following: + * + * - `SDL_MESSAGEBOX_ERROR`: error dialog + * - `SDL_MESSAGEBOX_WARNING`: warning dialog + * - `SDL_MESSAGEBOX_INFORMATION`: informational dialog + * + * This function should be called on the thread that created the parent + * window, or on the main thread if the messagebox has no parent. It will + * block execution of that thread until the user clicks a button or closes the + * messagebox. + * + * This function may be called at any time, even before SDL_Init(). This makes + * it useful for reporting errors like a failure to create a renderer or + * OpenGL context. + * + * On X11, SDL rolls its own dialog box with X11 primitives instead of a + * formal toolkit like GTK+ or Qt. + * + * Note that if SDL_Init() would fail because there isn't any available video + * target, this function is likely to fail for the same reasons. If this is a + * concern, check the return value from this function and fall back to writing + * to stderr if you can. + * + * \param flags an SDL_MessageBoxFlags value. + * \param title UTF-8 title text. + * \param message UTF-8 message text. + * \param window the parent window, or nil for no parent. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ShowMessageBox + } +function SDL_ShowSimpleMessageBox(flags: TSDL_MessageBoxFlags; title: PAnsiChar; message: PAnsiChar; window: PSDL_Window): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ShowSimpleMessageBox' {$ENDIF} {$ENDIF}; + From 5efa184d09213286460edef34bcf05bc829a4478 Mon Sep 17 00:00:00 2001 From: Matthias Date: Fri, 7 Feb 2025 00:00:39 +0100 Subject: [PATCH 12/18] Add SDL_misc.inc --- units/SDL3.pas | 1 + units/SDL_misc.inc | 47 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+) create mode 100644 units/SDL_misc.inc diff --git a/units/SDL3.pas b/units/SDL3.pas index 48d0ef4..54c74a8 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -82,6 +82,7 @@ interface {$I SDL_locale.inc} // 3.2.0 {$I SDL_guid.inc} // 3.1.6-prev {$I SDL_hints.inc} // 3.2.0 +{$I SDL_misc.inc} // 3.2.0 {$I SDL_stdinc.inc} // 3.1.6-prev (unfinished) {$I SDL_loadso.inc} // 3.2.0 {$I SDL_rect.inc} // 3.1.6-prev diff --git a/units/SDL_misc.inc b/units/SDL_misc.inc new file mode 100644 index 0000000..d0133f8 --- /dev/null +++ b/units/SDL_misc.inc @@ -0,0 +1,47 @@ +{ + This file is part of: + + SDL3 for Pascal + (https://github.com/PascalGameDevelopment/SDL3-for-Pascal) + SPDX-License-Identifier: Zlib +} + +{* + * # CategoryMisc + * + * SDL API functions that don't fit elsewhere. + } + +{* + * Open a URL/URI in the browser or other appropriate + external application. + * + * Open a URL in a separate, system-provided application. How this works will + * vary wildly depending on the platform. This will likely launch what makes + * sense to handle a specific URL's protocol (a web browser for `http://`, + * etc), but it might also be able to launch file managers for directories and + * other things. + * + * What happens when you open a URL varies wildly as well: your game window + * may lose focus (and may or may not lose focus if your game was fullscreen + * or grabbing input at the time). On mobile devices, your app will likely + * move to the background or your process might be paused. Any given platform + * may or may not handle a given URL. + * + * If this is unimplemented (or simply unavailable) for a platform, this will + * fail with an error. A successful result does not mean the URL loaded, just + * that we launched _something_ to handle it (or at least believe we did). + * + * All this to say: this function can be useful, but you should definitely + * test it on every platform you target. + * + * \param url a valid URL/URI to open. Use `file:///full/path/to/file` for + * local files, if supported. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_OpenURL(url: PAnsiChar): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_OpenURL' {$ENDIF} {$ENDIF}; + From e4369ef09fcca63e3162f60465c595711ab35ed5 Mon Sep 17 00:00:00 2001 From: Matthias Date: Fri, 7 Feb 2025 00:03:52 +0100 Subject: [PATCH 13/18] Add SDL_metal.inc --- units/SDL3.pas | 1 + units/SDL_metal.inc | 79 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 80 insertions(+) create mode 100644 units/SDL_metal.inc diff --git a/units/SDL3.pas b/units/SDL3.pas index 54c74a8..de3e09a 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -119,6 +119,7 @@ interface {$I SDL_filesystem.inc} // 3.2.0 {$I SDL_atomic.inc} // 3.2.0 {$I SDL_hidapi.inc} // 3.2.0 +{$I SDL_metal.inc} // 3.2.0 diff --git a/units/SDL_metal.inc b/units/SDL_metal.inc new file mode 100644 index 0000000..875756b --- /dev/null +++ b/units/SDL_metal.inc @@ -0,0 +1,79 @@ +{ + This file is part of: + + SDL3 for Pascal + (https://github.com/PascalGameDevelopment/SDL3-for-Pascal) + SPDX-License-Identifier: Zlib +} + +{* + * # CategoryMetal + * + * Functions to creating Metal layers and views on SDL windows. + * + * This provides some platform-specific glue for Apple platforms. Most macOS + * and iOS apps can use SDL without these functions, but this API they can be + * useful for specific OS-level integration tasks. + } + +{* + * A handle to a CAMetalLayer-backed NSView (macOS) or UIView (iOS/tvOS). + * + * \since This datatype is available since SDL 3.2.0. + } +type + PPSDL_MetalView = ^PSDL_MetalView; + PSDL_MetalView = ^TSDL_MetalView; + TSDL_MetalView = Pointer; + +{* + * \name Metal support functions + } + +{* + * Create a CAMetalLayer-backed NSView/UIView and attach it to the specified + * window. + * + * On macOS, this does *not* associate a MTLDevice with the CAMetalLayer on + * its own. It is up to user code to do that. + * + * The returned handle can be casted directly to a NSView or UIView. To access + * the backing CAMetalLayer, call SDL_Metal_GetLayer(). + * + * \param window the window. + * \returns handle NSView or UIView. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Metal_DestroyView + * \sa SDL_Metal_GetLayer + } +function SDL_Metal_CreateView(window: PSDL_Window): TSDL_MetalView; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_Metal_CreateView' {$ENDIF} {$ENDIF}; + +{* + * Destroy an existing SDL_MetalView object. + * + * This should be called before SDL_DestroyWindow, if SDL_Metal_CreateView was + * called after SDL_CreateWindow. + * + * \param view the SDL_MetalView object. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Metal_CreateView + } +procedure SDL_Metal_DestroyView(view: TSDL_MetalView); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_Metal_DestroyView' {$ENDIF} {$ENDIF}; + +{* + * Get a Pointer to the backing CAMetalLayer for the given view. + * + * \param view the SDL_MetalView object. + * \returns a Pointer. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_Metal_GetLayer(view: TSDL_MetalView): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_Metal_GetLayer' {$ENDIF} {$ENDIF}; + From 63b15294315fff1ec4d6ade52987895bdc05d446 Mon Sep 17 00:00:00 2001 From: Matthias Date: Fri, 7 Feb 2025 09:55:22 +0100 Subject: [PATCH 14/18] Add SDL_platform.inc --- units/SDL3.pas | 1 + units/SDL_platform.inc | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 35 insertions(+) create mode 100644 units/SDL_platform.inc diff --git a/units/SDL3.pas b/units/SDL3.pas index de3e09a..729c1ed 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -84,6 +84,7 @@ interface {$I SDL_hints.inc} // 3.2.0 {$I SDL_misc.inc} // 3.2.0 {$I SDL_stdinc.inc} // 3.1.6-prev (unfinished) +{$I SDL_platform.inc} // 3.2.0 {$I SDL_loadso.inc} // 3.2.0 {$I SDL_rect.inc} // 3.1.6-prev {$I SDL_properties.inc} // 3.1.6-prev diff --git a/units/SDL_platform.inc b/units/SDL_platform.inc new file mode 100644 index 0000000..64c57f2 --- /dev/null +++ b/units/SDL_platform.inc @@ -0,0 +1,34 @@ +{ + This file is part of: + + SDL3 for Pascal + (https://github.com/PascalGameDevelopment/SDL3-for-Pascal) + SPDX-License-Identifier: Zlib +} + +{* + * # CategoryPlatform + * + * SDL provides a means to identify the app's platform, both at compile time + * and runtime. + } + +{* + * Get the name of the platform. + * + * Here are the names returned for some (but not all) supported platforms: + * + * - "Windows" + * - "macOS" + * - "Linux" + * - "iOS" + * - "Android" + * + * \returns the name of the platform. If the correct platform name is not + * available, returns a string beginning with the text "Unknown". + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetPlatform: PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetPlatform' {$ENDIF} {$ENDIF}; + From 871556a4d846954334ea4579290af973424c340e Mon Sep 17 00:00:00 2001 From: Matthias Date: Fri, 7 Feb 2025 10:59:58 +0100 Subject: [PATCH 15/18] Add SDL_vulkan.inc --- units/SDL3.pas | 1 + units/SDL_vulkan.inc | 272 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 273 insertions(+) create mode 100644 units/SDL_vulkan.inc diff --git a/units/SDL3.pas b/units/SDL3.pas index 729c1ed..f32dced 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -121,6 +121,7 @@ interface {$I SDL_atomic.inc} // 3.2.0 {$I SDL_hidapi.inc} // 3.2.0 {$I SDL_metal.inc} // 3.2.0 +{$I SDL_vulkan.inc} // 3.2.0 diff --git a/units/SDL_vulkan.inc b/units/SDL_vulkan.inc new file mode 100644 index 0000000..49b8ee3 --- /dev/null +++ b/units/SDL_vulkan.inc @@ -0,0 +1,272 @@ +{ + This file is part of: + + SDL3 for Pascal + (https://github.com/PascalGameDevelopment/SDL3-for-Pascal) + SPDX-License-Identifier: Zlib +} + +{* + * # CategoryVulkan + * + * Functions for creating Vulkan surfaces on SDL windows. + * + * For the most part, Vulkan operates independent of SDL, but it benefits from + * a little support during setup. + * + * Use SDL_Vulkan_GetInstanceExtensions() to get platform-specific bits for + * creating a VkInstance, then SDL_Vulkan_GetVkGetInstanceProcAddr() to get + * the appropriate function for querying Vulkan entry points. Then + * SDL_Vulkan_CreateSurface() will get you the final pieces you need to + * prepare for rendering into an SDL_Window with Vulkan. + * + * Unlike OpenGL, most of the details of "context" creation and window buffer + * swapping are handled by the Vulkan API directly, so SDL doesn't provide + * Vulkan equivalents of SDL_GL_SwapWindow(), etc; they aren't necessary. + } + +{ #note : SDL3-for-Pascal: The following comment includes the original C code. } +{ Avoid including vulkan.h, don't define VkInstance if it's already included } +{ + #ifdef VULKAN_H_ + #define NO_SDL_VULKAN_TYPEDEFS + #endif + #ifndef NO_SDL_VULKAN_TYPEDEFS + #define VK_DEFINE_HANDLE(object) typedef struct object##_T* object; + + #if defined(__LP64__) || defined(_WIN64) || defined(__x86_64__) || defined(_M_X64) || defined(__ia64) || defined (_M_IA64) || defined(__aarch64__) || defined(__powerpc64__) + #define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef struct object##_T *object; + #else + #define VK_DEFINE_NON_DISPATCHABLE_HANDLE(object) typedef uint64_t object; + #endif + + VK_DEFINE_HANDLE(VkInstance) + VK_DEFINE_HANDLE(VkPhysicalDevice) + VK_DEFINE_NON_DISPATCHABLE_HANDLE(VkSurfaceKHR) + struct VkAllocationCallbacks; +} +{ #todo : Is there a common compiler flag in the Vulkan bindings for Pascal? Couldn't find any common one. Examine. } +{$IFDEF VULKAN} + {$DEFINE NO_SDL_VULKAN_TYPEDEFS} +{$ENDIF} +{$IFNDEF NO_SDL_VULKAN_TYPEDEFS} +type + PVkInstance = ^TVkInstance; + TVkInstance = ^TVkInstance_T; + TVkInstance_T = record + end; + PVkPhysicalDevice = ^TVkPhysicalDevice; + TVkPhysicalDevice = ^TVkPhysicalDevice_T; + TVkPhysicalDevice_T = record + end; + PVkSurfaceKHR = ^TVkSurfaceKHR; + TVkSurfaceKHR = ^TVkSurfaceKHR_T; + TVkSurfaceKHR_T = record + end; +{$ENDIF} +type + PPVkAllocationCallbacks = ^PVkAllocationCallbacks; + PVkAllocationCallbacks = ^TVkAllocationCallbacks; + TVkAllocationCallbacks = record + {undefined structure} + end; + +{* + * \name Vulkan support functions + } + +{* + * Dynamically load the Vulkan loader library. + * + * This should be called after initializing the video driver, but before + * creating any Vulkan windows. If no Vulkan loader library is loaded, the + * default library will be loaded upon creation of the first Vulkan window. + * + * SDL keeps a counter of how many times this function has been successfully + * called, so it is safe to call this function multiple times, so long as it + * is eventually paired with an equivalent number of calls to + * SDL_Vulkan_UnloadLibrary. The `path` argument is ignored unless there is no + * library currently loaded, and and the library isn't actually unloaded until + * there have been an equivalent number of calls to SDL_Vulkan_UnloadLibrary. + * + * It is fairly common for Vulkan applications to link with libvulkan instead + * of explicitly loading it at run time. This will work with SDL provided the + * application links to a dynamic library and both it and SDL use the same + * search path. + * + * If you specify a non-nil `path`, an application should retrieve all of the + * Vulkan functions it uses from the dynamic library using + * SDL_Vulkan_GetVkGetInstanceProcAddr unless you can guarantee `path` points + * to the same vulkan loader library the application linked to. + * + * On Apple devices, if `path` is nil, SDL will attempt to find the + * `vkGetInstanceProcAddr` address within all the Mach-O images of the current + * process. This is because it is fairly common for Vulkan applications to + * link with libvulkan (and historically MoltenVK was provided as a static + * library). If it is not found, on macOS, SDL will attempt to load + * `vulkan.framework/vulkan`, `libvulkan.1.dylib`, + * `MoltenVK.framework/MoltenVK`, and `libMoltenVK.dylib`, in that order. On + * iOS, SDL will attempt to load `libMoltenVK.dylib`. Applications using a + * dynamic framework or .dylib must ensure it is included in its application + * bundle. + * + * On non-Apple devices, application linking with a static libvulkan is not + * supported. Either do not link to the Vulkan loader or link to a dynamic + * library version. + * + * \param path the platform dependent Vulkan loader library name or nil. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Vulkan_GetVkGetInstanceProcAddr + * \sa SDL_Vulkan_UnloadLibrary + } +function SDL_Vulkan_LoadLibrary(path: PAnsiChar): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_Vulkan_LoadLibrary' {$ENDIF} {$ENDIF}; + +{* + * Get the address of the `vkGetInstanceProcAddr` function. + * + * This should be called after either calling SDL_Vulkan_LoadLibrary() or + * creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag. + * + * The actual type of the returned function Pointer is + * PFN_vkGetInstanceProcAddr, but that isn't available because the Vulkan + * headers are not included here. You should cast the return value of this + * function to that type, e.g. + * + * `vkGetInstanceProcAddr = + * (PFN_vkGetInstanceProcAddr)SDL_Vulkan_GetVkGetInstanceProcAddr();` + * + * \returns the function Pointer for `vkGetInstanceProcAddr` or nil on + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_Vulkan_GetVkGetInstanceProcAddr: TSDL_FunctionPointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_Vulkan_GetVkGetInstanceProcAddr' {$ENDIF} {$ENDIF}; + +{* + * Unload the Vulkan library previously loaded by SDL_Vulkan_LoadLibrary(). + * + * SDL keeps a counter of how many times this function has been called, so it + * is safe to call this function multiple times, so long as it is paired with + * an equivalent number of calls to SDL_Vulkan_LoadLibrary. The library isn't + * actually unloaded until there have been an equivalent number of calls to + * SDL_Vulkan_UnloadLibrary. + * + * Once the library has actually been unloaded, if any Vulkan instances + * remain, they will likely crash the program. Clean up any existing Vulkan + * resources, and destroy appropriate windows, renderers and GPU devices + * before calling this function. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Vulkan_LoadLibrary + } +procedure SDL_Vulkan_UnloadLibrary; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_Vulkan_UnloadLibrary' {$ENDIF} {$ENDIF}; + +{* + * Get the Vulkan instance extensions needed for vkCreateInstance. + * + * This should be called after either calling SDL_Vulkan_LoadLibrary() or + * creating an SDL_Window with the `SDL_WINDOW_VULKAN` flag. + * + * On return, the variable pointed to by `count` will be set to the number of + * elements returned, suitable for using with + * VkInstanceCreateInfo:: enabledExtensionCount, and the returned array can be + * used with VkInstanceCreateInfo:: ppEnabledExtensionNames, for calling + * Vulkan's vkCreateInstance API. + * + * You should not free the returned array; it is owned by SDL. + * + * \param count a Pointer filled in with the number of extensions returned. + * \returns an array of extension name strings on success, nil on failure; + * call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Vulkan_CreateSurface + } +function SDL_Vulkan_GetInstanceExtensions(count: pcuint32):PPAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_Vulkan_GetInstanceExtensions' {$ENDIF} {$ENDIF}; + +{* + * Create a Vulkan rendering surface for a window. + * + * The `window` must have been created with the `SDL_WINDOW_VULKAN` flag and + * `instance` must have been created with extensions returned by + * SDL_Vulkan_GetInstanceExtensions() enabled. + * + * If `allocator` is nil, Vulkan will use the system default allocator. This + * argument is passed directly to Vulkan and isn't used by SDL itself. + * + * \param window the window to which to attach the Vulkan surface. + * \param instance the Vulkan instance handle. + * \param allocator a VkAllocationCallbacks struct, which lets the app set the + * allocator that creates the surface. Can be nil. + * \param surface a Pointer to a VkSurfaceKHR handle to output the newly + * created surface. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Vulkan_GetInstanceExtensions + * \sa SDL_Vulkan_DestroySurface + } +function SDL_Vulkan_CreateSurface(window: PSDL_Window; instance: TVkInstance; allocator: PVkAllocationCallbacks; surface: PVkSurfaceKHR): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_Vulkan_CreateSurface' {$ENDIF} {$ENDIF}; + +{* + * Destroy the Vulkan rendering surface of a window. + * + * This should be called before SDL_DestroyWindow, if SDL_Vulkan_CreateSurface + * was called after SDL_CreateWindow. + * + * The `instance` must have been created with extensions returned by + * SDL_Vulkan_GetInstanceExtensions() enabled and `surface` must have been + * created successfully by an SDL_Vulkan_CreateSurface() call. + * + * If `allocator` is nil, Vulkan will use the system default allocator. This + * argument is passed directly to Vulkan and isn't used by SDL itself. + * + * \param instance the Vulkan instance handle. + * \param surface vkSurfaceKHR handle to destroy. + * \param allocator a VkAllocationCallbacks struct, which lets the app set the + * allocator that destroys the surface. Can be nil. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Vulkan_GetInstanceExtensions + * \sa SDL_Vulkan_CreateSurface + } +procedure SDL_Vulkan_DestroySurface(instance: TVkInstance; surface: TVkSurfaceKHR; allocator: PVkAllocationCallbacks); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_Vulkan_DestroySurface' {$ENDIF} {$ENDIF}; + +{* + * Query support for presentation via a given physical device and queue + * family. + * + * The `instance` must have been created with extensions returned by + * SDL_Vulkan_GetInstanceExtensions() enabled. + * + * \param instance the Vulkan instance handle. + * \param physicalDevice a valid Vulkan physical device handle. + * \param queueFamilyIndex a valid queue family index for the given physical + * device. + * \returns true if supported, false if unsupported or an error occurred. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Vulkan_GetInstanceExtensions + } +function SDL_Vulkan_GetPresentationSupport(instance: TVkInstance; physicalDevice: TVkPhysicalDevice; queueFamilyIndex: cuint32): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_Vulkan_GetPresentationSupport' {$ENDIF} {$ENDIF}; From 3f46437abd03d7e75423d2f773b3f6a966caee94 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sun, 9 Feb 2025 23:34:49 +0100 Subject: [PATCH 16/18] Add SDL_thread.inc --- units/SDL3.pas | 12 + units/SDL_thread.inc | 600 +++++++++++++++++++++++++++++++++++++++++++ units/sdl.inc | 5 + 3 files changed, 617 insertions(+) create mode 100644 units/SDL_thread.inc diff --git a/units/SDL3.pas b/units/SDL3.pas index f32dced..c60f9c7 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -122,6 +122,7 @@ interface {$I SDL_hidapi.inc} // 3.2.0 {$I SDL_metal.inc} // 3.2.0 {$I SDL_vulkan.inc} // 3.2.0 +{$I SDL_thread.inc} // 3.2.0 @@ -337,5 +338,16 @@ function SDL_AtomicDecRef(a: PSDL_AtomicInt): cbool; SDL_AtomicDecRef:=(SDL_AddAtomicInt(a,-1)=1); end; +{ Macros from SDL_thread.h } +function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; data: Pointer): PSDL_Thread; +begin + SDL_CreateThread:=SDL_CreateThreadRuntime(fn,name,data,TSDL_FunctionPointer(SDL_BeginThreadFunction),TSDL_FunctionPointer(SDL_EndThreadFunction)); +end; + +function SDL_CreateThreadWithProperties(props: TSDL_PropertiesID): PSDL_Thread; +begin + SDL_CreateThreadWithProperties:=SDL_CreateThreadWithPropertiesRuntime(props,TSDL_FunctionPointer(SDL_BeginThreadFunction),TSDL_FunctionPointer(SDL_EndThreadFunction)); +end; + end. diff --git a/units/SDL_thread.inc b/units/SDL_thread.inc new file mode 100644 index 0000000..8864b11 --- /dev/null +++ b/units/SDL_thread.inc @@ -0,0 +1,600 @@ +{ + This file is part of: + + SDL3 for Pascal + (https://github.com/PascalGameDevelopment/SDL3-for-Pascal) + SPDX-License-Identifier: Zlib +} + +{* + * # CategoryThread + * + * SDL offers cross-platform thread management functions. These are mostly + * concerned with starting threads, setting their priority, and dealing with + * their termination. + * + * In addition, there is support for Thread Local Storage (data that is unique + * to each thread, but accessed from a single key). + * + * On platforms without thread support (such as Emscripten when built without + * pthreads), these functions still exist, but things like SDL_CreateThread() + * will report failure without doing anything. + * + * If you're going to work with threads, you almost certainly need to have a + * good understanding of [CategoryMutex](CategoryMutex) as well. + } + +{* + * The SDL thread object. + * + * These are opaque data. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateThread + * \sa SDL_WaitThread + } +type + PPSDL_Thread = ^PSDL_Thread; + PSDL_Thread = type Pointer; + +{* + * A unique numeric ID that identifies a thread. + * + * These are different from SDL_Thread objects, which are generally what an + * application will operate on, but having a way to uniquely identify a thread + * can be useful at times. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GetThreadID + * \sa SDL_GetCurrentThreadID + } +type + PPSDL_ThreadID = ^PSDL_ThreadID; + PSDL_ThreadID = ^TSDL_ThreadID; + TSDL_ThreadID = cuint64; + +{* + * Thread local storage ID. + * + * 0 is the invalid ID. An app can create these and then set data for these + * IDs that is unique to each thread. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GetTLS + * \sa SDL_SetTLS + } +type + PPSDL_TLSID = ^PSDL_TLSID; + PSDL_TLSID = ^TSDL_TLSID; + TSDL_TLSID = TSDL_AtomicInt; + +{* + * The SDL thread priority. + * + * SDL will make system changes as necessary in order to apply the thread + * priority. Code which attempts to control thread state related to priority + * should be aware that calling SDL_SetCurrentThreadPriority may alter such + * state. SDL_HINT_THREAD_PRIORITY_POLICY can be used to control aspects of + * this behavior. + * + * \since This enum is available since SDL 3.2.0. + } +type + PPSDL_ThreadPriority = ^PSDL_ThreadPriority; + PSDL_ThreadPriority = ^TSDL_ThreadPriority; + TSDL_ThreadPriority = type Integer; +const + SDL_THREAD_PRIORITY_LOW = TSDL_ThreadPriority(0); + SDL_THREAD_PRIORITY_NORMAL = TSDL_ThreadPriority(1); + SDL_THREAD_PRIORITY_HIGH = TSDL_ThreadPriority(2); + SDL_THREAD_PRIORITY_TIME_CRITICAL = TSDL_ThreadPriority(3); + +{* + * The SDL thread state. + * + * The current state of a thread can be checked by calling SDL_GetThreadState. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_GetThreadState + } +type + PPSDL_ThreadState = ^PSDL_ThreadState; + PSDL_ThreadState = ^TSDL_ThreadState; + TSDL_ThreadState = type Integer; +const + SDL_THREAD_UNKNOWN = TSDL_ThreadState(0); {*< The thread is not valid } + SDL_THREAD_ALIVE = TSDL_ThreadState(1); {*< The thread is currently running } + SDL_THREAD_DETACHED = TSDL_ThreadState(2); {*< The thread is detached and can't be waited on } + SDL_THREAD_COMPLETE = TSDL_ThreadState(3); {*< The thread has finished and should be cleaned up with SDL_WaitThread() } + +{* + * The function passed to SDL_CreateThread() as the new thread's entry point. + * + * \param data what was passed as `data` to SDL_CreateThread(). + * \returns a value that can be reported through SDL_WaitThread(). + * + * \since This datatype is available since SDL 3.2.0. + } +type + TSDL_ThreadFunction = function(data: Pointer): cint; cdecl; + +{ + * Note that these aren't the correct function signatures in this block, but + * this is what the API reference manual should look like for all intents and + * purposes. + * + * Technical details, not for the wiki (hello, header readers!)... + * + * On Windows (and maybe other platforms), a program might use a different + * C runtime than its libraries. Or, in SDL's case, it might use a C runtime + * while SDL uses none at all. + * + * C runtimes expect to initialize thread-specific details when a new thread + * is created, but to do this in SDL_CreateThread would require SDL to know + * intimate details about the caller's C runtime, which is not possible. + * + * So SDL_CreateThread has two extra parameters, which are + * hidden at compile time by macros: the C runtime's `_beginthreadex` and + * `_endthreadex` entry points. If these are not nil, they are used to spin + * and terminate the new thread; otherwise the standard Win32 `CreateThread` + * function is used. When `SDL_CreateThread` is called from a compiler that + * needs this C runtime thread init function, macros insert the appropriate + * function pointers for SDL_CreateThread's caller (which might be a different + * compiler with a different runtime in different calls to SDL_CreateThread!). + * + * SDL_BeginThreadFunction defaults to `_beginthreadex` on Windows (and nil + * everywhere else), but apps that have extremely specific special needs can + * define this to something else and the SDL headers will use it, passing the + * app-defined value to SDL_CreateThread calls. Redefine this with caution! + * + * Platforms that don't need _beginthread stuff (most everything) will fail + * SDL_CreateThread with an error if these pointers _aren't_ nil. + * + * Unless you are doing something extremely complicated, like perhaps a + * language binding, **you should never deal with this directly**. Let SDL's + * macros handle this platform-specific detail transparently! + } + +{* + * Create a new thread with a default stack size. + * + * This is a convenience function, equivalent to calling + * SDL_CreateThreadWithProperties with the following properties set: + * + * - `SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER`: `fn` + * - `SDL_PROP_THREAD_CREATE_NAME_STRING`: `name` + * - `SDL_PROP_THREAD_CREATE_USERDATA_POINTER`: `data` + * + * Note that this "function" is actually a macro that calls an internal + * function with two extra parameters not listed here; they are hidden through + * preprocessor macros and are needed to support various C runtimes at the + * point of the function call. Language bindings that aren't using the C + * headers will need to deal with this. + * + * Usually, apps should just call this function the same way on every platform + * and let the macros hide the details. + * + * \param fn the SDL_ThreadFunction function to call in the new thread. + * \param name the name of the thread. + * \param data a Pointer that is passed to `fn`. + * \returns an opaque Pointer to the new thread object on success, nil if the + * new thread could not be created; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateThreadWithProperties + * \sa SDL_WaitThread + } +{ #todo : SDL3-for-Pascal: According to the description we should use the + macros directly and take care of different "runtimes" manually. + Is this correct? } +//function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; data: Pointer): PSDL_Thread; cdecl; +// external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThread' {$ENDIF} {$ENDIF}; + +{* + * Create a new thread with with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER`: an SDL_ThreadFunction + * value that will be called at the start of the new thread's life. + * Required. + * - `SDL_PROP_THREAD_CREATE_NAME_STRING`: the name of the new thread, which + * might be available to debuggers. Optional, defaults to nil. + * - `SDL_PROP_THREAD_CREATE_USERDATA_POINTER`: an arbitrary app-defined + * Pointer, which is passed to the entry function on the new thread, as its + * only parameter. Optional, defaults to nil. + * - `SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER`: the size, in bytes, of the new + * thread's stack. Optional, defaults to 0 (system-defined default). + * + * SDL makes an attempt to report `SDL_PROP_THREAD_CREATE_NAME_STRING` to the + * system, so that debuggers can display it. Not all platforms support this. + * + * Thread naming is a little complicated: Most systems have very small limits + * for the string length (Haiku has 32 bytes, Linux currently has 16, Visual + * C++ 6.0 has _nine_!), and possibly other arbitrary rules. You'll have to + * see what happens with your system's debugger. The name should be UTF-8 (but + * using the naming limits of C identifiers is a better bet). There are no + * requirements for thread naming conventions, so long as the string is + * null-terminated UTF-8, but these guidelines are helpful in choosing a name: + * + * https://stackoverflow.com/questions/149932/naming-conventions-for-threads + * + * If a system imposes requirements, SDL will try to munge the string for it + * (truncate, etc), but the original string contents will be available from + * SDL_GetThreadName(). + * + * The size (in bytes) of the new stack can be specified with + * `SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER`. Zero means "use the system + * default" which might be wildly different between platforms. x86 Linux + * generally defaults to eight megabytes, an embedded device might be a few + * kilobytes instead. You generally need to specify a stack that is a multiple + * of the system's page size (in many cases, this is 4 kilobytes, but check + * your system documentation). + * + * Note that this "function" is actually a macro that calls an internal + * function with two extra parameters not listed here; they are hidden through + * preprocessor macros and are needed to support various C runtimes at the + * point of the function call. Language bindings that aren't using the C + * headers will need to deal with this. + * + * The actual symbol in SDL is `SDL_CreateThreadWithPropertiesRuntime`, so + * there is no symbol clash, but trying to load an SDL shared library and look + * for "SDL_CreateThreadWithProperties" will fail. + * + * Usually, apps should just call this function the same way on every platform + * and let the macros hide the details. + * + * \param props the properties to use. + * \returns an opaque Pointer to the new thread object on success, nil if the + * new thread could not be created; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateThread + * \sa SDL_WaitThread + } +{ #todo : SDL3-for-Pascal: According to the description we should use the + macros directly and take care of different "runtimes" manually. + Is this correct? } +//function SDL_CreateThreadWithProperties(props: TSDL_PropertiesID): PSDL_Thread; cdecl; +// external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThreadWithProperties' {$ENDIF} {$ENDIF}; + +{ #note : SDL3-for-Pascal: These constants are defined again at the macro + definitions. } +//const +// SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER = 'SDL.thread.create.entry_function'; +// SDL_PROP_THREAD_CREATE_NAME_STRING = 'SDL.thread.create.name'; +// SDL_PROP_THREAD_CREATE_USERDATA_POINTER = 'SDL.thread.create.userdata'; +// SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER = 'SDL.thread.create.stacksize'; + + +{ The real implementation, hidden from the wiki, so it can show this as real functions that don't have macro magic. } + +{ #note : SDL3-for-Pascal: + + In Windows begin/end thread functions are defined by _beginthreadex + and _endthreadex. On other systems they are not defined, hence NIL. + + #todo : SDL3-for-Pascal: + + We treat them as nil constants on other systems AND for Windows. + Implementation for Windows is needed. + + A starting point and source are added. + Unfortunately, if (T)SDL_BeginThreadFunction is typed, + the calling macro functions SDL_CreateThread and + SDL_CreateThreadWithProperties stop working, as they expect a + cast of TSDL_FunctionPointer; which is possible for a nil constant + but not for another type in Pascal. + } +{$IFDEF SDL_PLATFORM_WINDOWS} + {$IFNDEF SDL_BeginThreadFunction} + { Source: https://learn.microsoft.com/de-de/cpp/c-runtime-library/reference/beginthread-beginthreadex?view=msvc-170 } + { NATIVE CODE: uintptr_t _beginthreadex(void *security, unsigned stack_size, unsigned ( __stdcall *start_address )( void * ), void *arglist, unsigned initflag, unsigned *thrdaddr); } + //type + // start_address_func = function(parameter:Pointer):cuint; stdcall; + // _beginthreadex = function(security:Pointer; stack_size:cuint; start_address: start_address_func; arglist: Pointer; initflat:cuint; thrdaddr:pcuint): cuintptr_t; cdecl; + // TSDL_BeginThreadFunction = _beginthreadex; + const + SDL_BeginThreadFunction = nil; + {$DEFINE SDL_BeginThreadFunction} + {$ENDIF} + {$IFNDEF SDL_EndThreadFunction} + { Source: https://learn.microsoft.com/de-de/cpp/c-runtime-library/reference/endthread-endthreadex?view=msvc-170 } + { void _endthreadex(unsigned retval); } + //type + // _endthreadex = procedure(retval:cuint); cdecl; + // TSDL_EndThreadFunction = _endthreadex; + const + SDL_EndThreadFunction = nil; + {$DEFINE SDL_EndThreadFunction} + {$ENDIF} +{$ENDIF} + +{ currently no other platforms than Windows use _beginthreadex/_endthreadex things. } +{$IFNDEF SDL_BeginThreadFunction} + const + SDL_BeginThreadFunction = nil; +{$DEFINE SDL_BeginThreadFunction} +{$ENDIF} + +{$IFNDEF SDL_EndThreadFunction} + const + SDL_EndThreadFunction = nil; +{$DEFINE SDL_BeginThreadFunction} +{$ENDIF} + +{ These are the actual functions exported from SDL! Don't use them directly! Use the SDL_CreateThread and SDL_CreateThreadWithProperties macros! } +{* + * The actual entry point for SDL_CreateThread. + * + * \param fn the SDL_ThreadFunction function to call in the new thread + * \param name the name of the thread + * \param data a Pointer that is passed to `fn` + * \param pfnBeginThread the C runtime's _beginthreadex (or whatnot). Can be nil. + * \param pfnEndThread the C runtime's _endthreadex (or whatnot). Can be nil. + * \returns an opaque Pointer to the new thread object on success, nil if the + * new thread could not be created; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_CreateThreadRuntime(fn: TSDL_ThreadFunction; name: PAnsiChar; data: Pointer; pfnBeginThread: TSDL_FunctionPointer; pfnEndThread: TSDL_FunctionPointer): PSDL_Thread; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThreadRuntime' {$ENDIF} {$ENDIF}; + +{* + * The actual entry point for SDL_CreateThreadWithProperties. + * + * \param props the properties to use + * \param pfnBeginThread the C runtime's _beginthreadex (or whatnot). Can be nil. + * \param pfnEndThread the C runtime's _endthreadex (or whatnot). Can be nil. + * \returns an opaque Pointer to the new thread object on success, nil if the + * new thread could not be created; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_CreateThreadWithPropertiesRuntime(props: TSDL_PropertiesID; pfnBeginThread: TSDL_FunctionPointer; pfnEndThread: TSDL_FunctionPointer): PSDL_Thread; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThreadWithPropertiesRuntime' {$ENDIF} {$ENDIF}; + + +function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; data: Pointer): PSDL_Thread; +function SDL_CreateThreadWithProperties(props: TSDL_PropertiesID): PSDL_Thread; +const + SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER = 'SDL.thread.create.entry_function'; + SDL_PROP_THREAD_CREATE_NAME_STRING = 'SDL.thread.create.name'; + SDL_PROP_THREAD_CREATE_USERDATA_POINTER = 'SDL.thread.create.userdata'; + SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER = 'SDL.thread.create.stacksize'; + +{* + * Get the thread name as it was specified in SDL_CreateThread(). + * + * \param thread the thread to query. + * \returns a Pointer to a UTF-8 string that names the specified thread, or + * nil if it doesn't have a name. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GetThreadName(thread: PSDL_Thread): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetThreadName' {$ENDIF} {$ENDIF}; + +{* + * Get the thread identifier for the current thread. + * + * This thread identifier is as reported by the underlying operating system. + * If SDL is running on a platform that does not support threads the return + * value will always be zero. + * + * This function also returns a valid thread ID when called from the main + * thread. + * + * \returns the ID of the current thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetThreadID + } +function SDL_GetCurrentThreadID: TSDL_ThreadID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetCurrentThreadID' {$ENDIF} {$ENDIF}; + +{* + * Get the thread identifier for the specified thread. + * + * This thread identifier is as reported by the underlying operating system. + * If SDL is running on a platform that does not support threads the return + * value will always be zero. + * + * \param thread the thread to query. + * \returns the ID of the specified thread, or the ID of the current thread if + * `thread` is nil. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetCurrentThreadID + } +function SDL_GetThreadID(thread: PSDL_Thread): TSDL_ThreadID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetThreadID' {$ENDIF} {$ENDIF}; + +{* + * Set the priority for the current thread. + * + * Note that some platforms will not let you alter the priority (or at least, + * promote the thread to a higher priority) at all, and some require you to be + * an administrator account. Be prepared for this to fail. + * + * \param priority the SDL_ThreadPriority to set. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_SetCurrentThreadPriority(priority: TSDL_ThreadPriority): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetCurrentThreadPriority' {$ENDIF} {$ENDIF}; + +{* + * Wait for a thread to finish. + * + * Threads that haven't been detached will remain until this function cleans + * them up. Not doing so is a resource leak. + * + * Once a thread has been cleaned up through this function, the SDL_Thread + * that references it becomes invalid and should not be referenced again. As + * such, only one thread may call SDL_WaitThread() on another. + * + * The return code from the thread function is placed in the area pointed to + * by `status`, if `status` is not nil. + * + * You may not wait on a thread that has been used in a call to + * SDL_DetachThread(). Use either that function or this one, but not both, or + * behavior is undefined. + * + * It is safe to pass a nil thread to this function; it is a no-op. + * + * Note that the thread Pointer is freed by this function and is not valid + * afterward. + * + * \param thread the SDL_Thread Pointer that was returned from the + * SDL_CreateThread() call that started this thread. + * \param status a Pointer filled in with the value returned from the thread + * function by its 'return', or -1 if the thread has been + * detached or isn't valid, may be nil. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateThread + * \sa SDL_DetachThread + } +procedure SDL_WaitThread(thread: PSDL_Thread; status: pcint); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WaitThread' {$ENDIF} {$ENDIF}; + +{* + * Get the current state of a thread. + * + * \param thread the thread to query. + * \returns the current state of a thread, or SDL_THREAD_UNKNOWN if the thread + * isn't valid. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ThreadState + } +function SDL_GetThreadState(thread: PSDL_Thread): TSDL_ThreadState; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetThreadState' {$ENDIF} {$ENDIF}; + +{* + * Let a thread clean up on exit without intervention. + * + * A thread may be "detached" to signify that it should not remain until + * another thread has called SDL_WaitThread() on it. Detaching a thread is + * useful for long-running threads that nothing needs to synchronize with or + * further manage. When a detached thread is done, it simply goes away. + * + * There is no way to recover the return code of a detached thread. If you + * need this, don't detach the thread and instead use SDL_WaitThread(). + * + * Once a thread is detached, you should usually assume the SDL_Thread isn't + * safe to reference again, as it will become invalid immediately upon the + * detached thread's exit, instead of remaining until someone has called + * SDL_WaitThread() to finally clean it up. As such, don't detach the same + * thread more than once. + * + * If a thread has already exited when passed to SDL_DetachThread(), it will + * stop waiting for a call to SDL_WaitThread() and clean up immediately. It is + * not safe to detach a thread that might be used with SDL_WaitThread(). + * + * You may not call SDL_WaitThread() on a thread that has been detached. Use + * either that function or this one, but not both, or behavior is undefined. + * + * It is safe to pass nil to this function; it is a no-op. + * + * \param thread the SDL_Thread Pointer that was returned from the + * SDL_CreateThread() call that started this thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateThread + * \sa SDL_WaitThread + } +procedure SDL_DetachThread(thread: PSDL_Thread); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DetachThread' {$ENDIF} {$ENDIF}; + +{* + * Get the current thread's value associated with a thread local storage ID. + * + * \param id a Pointer to the thread local storage ID, may not be nil. + * \returns the value associated with the ID for the current thread or nil if + * no value has been set; call SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_SetTLS + } +function SDL_GetTLS(id: PSDL_TLSID): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetTLS' {$ENDIF} {$ENDIF}; + +{* + * The callback used to cleanup data passed to SDL_SetTLS. + * + * This is called when a thread exits, to allow an app to free any resources. + * + * \param value a Pointer previously handed to SDL_SetTLS. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_SetTLS + } +type + TSDL_TLSDestructorCallback = procedure(value: Pointer); cdecl; + +{* + * Set the current thread's value associated with a thread local storage ID. + * + * If the thread local storage ID is not initialized (the value is 0), a new + * ID will be created in a thread-safe way, so all calls using a Pointer to + * the same ID will refer to the same local storage. + * + * Note that replacing a value from a previous call to this function on the + * same thread does _not_ call the previous value's destructor! + * + * `destructor` can be nil; it is assumed that `value` does not need to be + * cleaned up if so. + * + * \param id a Pointer to the thread local storage ID, may not be nil. + * \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 nil. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetTLS + } +function SDL_SetTLS(id: PSDL_TLSID; value: Pointer; destructor_: TSDL_TLSDestructorCallback): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetTLS' {$ENDIF} {$ENDIF}; + +{* + * Cleanup all TLS data for this thread. + * + * If you are creating your threads outside of SDL and then calling SDL + * functions, you should call this function before your thread exits, to + * properly clean up SDL memory. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + } +procedure SDL_CleanupTLS; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CleanupTLS' {$ENDIF} {$ENDIF}; + diff --git a/units/sdl.inc b/units/sdl.inc index b900529..6bf80dd 100644 --- a/units/sdl.inc +++ b/units/sdl.inc @@ -10,3 +10,8 @@ { Compiler defines } {$DEFINE SDL} // define "SDL" symbol {$DEFINE WANT_CWCHAR_T} // define C's wchar_t types + +{ SDL3 Compiler defines } +{$IFDEF WINDOWS} + {$DEFINE SDL_PLATFORM_WINDOWS} // used in SDL_thread.inc +{$ENDIF} From 0afa37140ab430240bfab2d2082c65b87f693502 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sun, 9 Feb 2025 23:43:26 +0100 Subject: [PATCH 17/18] Add SDL_process.inc --- units/SDL3.pas | 1 + units/SDL_process.inc | 411 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 412 insertions(+) create mode 100644 units/SDL_process.inc diff --git a/units/SDL3.pas b/units/SDL3.pas index c60f9c7..27b8ba4 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -123,6 +123,7 @@ interface {$I SDL_metal.inc} // 3.2.0 {$I SDL_vulkan.inc} // 3.2.0 {$I SDL_thread.inc} // 3.2.0 +{$I SDL_process.inc} // 3.2.0 diff --git a/units/SDL_process.inc b/units/SDL_process.inc new file mode 100644 index 0000000..fdc44be --- /dev/null +++ b/units/SDL_process.inc @@ -0,0 +1,411 @@ +{ + This file is part of: + + SDL3 for Pascal + (https://github.com/PascalGameDevelopment/SDL3-for-Pascal) + SPDX-License-Identifier: Zlib +} + +{* + * # 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! + } + +{* + * An opaque handle representing a system process. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + } +type + PPSDL_Process = ^PSDL_Process; + PSDL_Process = type Pointer; + +{* + * 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 nil, e.g.: + * + * ```c + * const char *args* = "myprogram", "argument", nil ; + * ``` + * + * 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 nil if the process + * couldn't be created. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + * \sa SDL_KillProcess + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + } +function SDL_CreateProcess(args: PPAnsiChar; pipe_stdio: cbool): PSDL_Process; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateProcess' {$ENDIF} {$ENDIF}; + +{* + * Description of where standard I/O should be directed when creating a + * process. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_INHERITED, it will go + * to the same place as the application's I/O stream. This is the default for + * standard output and standard error. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_NULL, it is connected + * to `NUL:` on Windows and `/dev/null` on POSIX systems. This is the default + * for standard input. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_APP, it is connected + * to a new SDL_IOStream that is available to the application. Standard input + * will be available as `SDL_PROP_PROCESS_STDIN_POINTER` and allows + * SDL_GetProcessInput(), standard output will be available as + * `SDL_PROP_PROCESS_STDOUT_POINTER` and allows SDL_ReadProcess() and + * SDL_GetProcessOutput(), and standard error will be available as + * `SDL_PROP_PROCESS_STDERR_POINTER` in the properties for the created + * process. + * + * If a standard I/O stream is set to SDL_PROCESS_STDIO_REDIRECT, it is + * connected to an existing SDL_IOStream provided by the application. Standard + * input is provided using `SDL_PROP_PROCESS_CREATE_STDIN_POINTER`, standard + * output is provided using `SDL_PROP_PROCESS_CREATE_STDOUT_POINTER`, and + * standard error is provided using `SDL_PROP_PROCESS_CREATE_STDERR_POINTER` + * in the creation properties. These existing streams should be closed by the + * application once the new process is created. + * + * In order to use an SDL_IOStream with SDL_PROCESS_STDIO_REDIRECT, it must + * have `SDL_PROP_IOSTREAM_WINDOWS_HANDLE_POINTER` or + * `SDL_PROP_IOSTREAM_FILE_DESCRIPTOR_NUMBER` set. This is true for streams + * representing files and process I/O. + * + * \since This enum is available since SDL 3.2.0. + * + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + } +type + PPSDL_ProcessIO = ^PSDL_ProcessIO; + PSDL_ProcessIO = ^TSDL_ProcessIO; + TSDL_ProcessIO = type Integer; +const + SDL_PROCESS_STDIO_INHERITED = TSDL_ProcessIO(0); {*< The I/O stream is inherited from the application. } + SDL_PROCESS_STDIO_NULL = TSDL_ProcessIO(1); {*< The I/O stream is ignored. } + SDL_PROCESS_STDIO_APP = TSDL_ProcessIO(2); {*< The I/O stream is connected to a new SDL_IOStream that the application can read or write } + SDL_PROCESS_STDIO_REDIRECT = TSDL_ProcessIO(3); {*< The I/O stream is redirected to an existing SDL_IOStream. } + +{* + * Create a new process with the specified properties. + * + * These are the supported properties: + * + * - `SDL_PROP_PROCESS_CREATE_ARGS_POINTER`: an array of strings containing + * the program to run, any arguments, and a nil Pointer, e.g. const char + * *args* = "myprogram", "argument", nil . 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 nil if the process + * couldn't be created. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_GetProcessProperties + * \sa SDL_ReadProcess + * \sa SDL_GetProcessInput + * \sa SDL_GetProcessOutput + * \sa SDL_KillProcess + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + } +function SDL_CreateProcessWithProperties(props: TSDL_PropertiesID): PSDL_Process; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateProcessWithProperties' {$ENDIF} {$ENDIF}; + +const + SDL_PROP_PROCESS_CREATE_ARGS_POINTER = 'SDL.process.create.args'; + SDL_PROP_PROCESS_CREATE_ENVIRONMENT_POINTER = 'SDL.process.create.environment'; + SDL_PROP_PROCESS_CREATE_STDIN_NUMBER = 'SDL.process.create.stdin_option'; + SDL_PROP_PROCESS_CREATE_STDIN_POINTER = 'SDL.process.create.stdin_source'; + SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER = 'SDL.process.create.stdout_option'; + SDL_PROP_PROCESS_CREATE_STDOUT_POINTER = 'SDL.process.create.stdout_source'; + SDL_PROP_PROCESS_CREATE_STDERR_NUMBER = 'SDL.process.create.stderr_option'; + SDL_PROP_PROCESS_CREATE_STDERR_POINTER = 'SDL.process.create.stderr_source'; + SDL_PROP_PROCESS_CREATE_STDERR_TO_STDOUT_BOOLEAN = 'SDL.process.create.stderr_to_stdout'; + SDL_PROP_PROCESS_CREATE_BACKGROUND_BOOLEAN = 'SDL.process.create.background'; + +{* + * Get the properties associated with a process. + * + * The following read-only properties are provided by SDL: + * + * - `SDL_PROP_PROCESS_PID_NUMBER`: the process ID of the process. + * - `SDL_PROP_PROCESS_STDIN_POINTER`: an SDL_IOStream that can be used to + * write input to the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_STDOUT_POINTER`: a non-blocking SDL_IOStream that can + * be used to read output from the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDOUT_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_STDERR_POINTER`: a non-blocking SDL_IOStream that can + * be used to read error output from the process, if it was created with + * `SDL_PROP_PROCESS_CREATE_STDERR_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * - `SDL_PROP_PROCESS_BACKGROUND_BOOLEAN`: true if the process is running in + * the background. + * + * \param process the process to query. + * \returns a valid property ID on success or 0 on failure; call + * SDL_GetError() for more information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + } +function SDL_GetProcessProperties(process: PSDL_Process): TSDL_PropertiesID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetProcessProperties' {$ENDIF} {$ENDIF}; + +const + SDL_PROP_PROCESS_PID_NUMBER = 'SDL.process.pid'; + SDL_PROP_PROCESS_STDIN_POINTER = 'SDL.process.stdin'; + SDL_PROP_PROCESS_STDOUT_POINTER = 'SDL.process.stdout'; + SDL_PROP_PROCESS_STDERR_POINTER = 'SDL.process.stderr'; + 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 + * nil. + * \param exitcode a Pointer filled in with the process exit code if the + * process has exited, may be nil. + * \returns the data or nil on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_DestroyProcess + } +function SDL_ReadProcess(process: PSDL_Process; datasize: pcsize_t; exitcode: pcint): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadProcess' {$ENDIF} {$ENDIF}; + +{* + * Get the SDL_IOStream associated with process standard input. + * + * The process must have been created with SDL_CreateProcess() and pipe_stdio + * set to true, or with SDL_CreateProcessWithProperties() and + * `SDL_PROP_PROCESS_CREATE_STDIN_NUMBER` set to `SDL_PROCESS_STDIO_APP`. + * + * Writing to this stream can return less data than expected if the process + * hasn't read its input. It may be blocked waiting for its output to be read, + * if so you may need to call SDL_GetProcessOutput() and read the output in + * parallel with writing input. + * + * \param process The process to get the input stream for. + * \returns the input stream or nil on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessOutput + } +function SDL_GetProcessInput(process: PSDL_Process): PSDL_IOStream; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetProcessInput' {$ENDIF} {$ENDIF}; + +{* + * 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 nil on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_GetProcessInput + } +function SDL_GetProcessOutput(process: PSDL_Process): PSDL_IOStream; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetProcessOutput' {$ENDIF} {$ENDIF}; + +{* + * Stop a process. + * + * \param process The process to stop. + * \param force true to terminate the process immediately, false to try to + * stop the process gracefully. In general you should try to stop + * the process gracefully first as terminating a process may + * leave it with half-written data or in some other unstable + * state. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_WaitProcess + * \sa SDL_DestroyProcess + } +function SDL_KillProcess(process: PSDL_Process; force: cbool): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_KillProcess' {$ENDIF} {$ENDIF}; + +{* + * Wait for a process to finish. + * + * This can be called multiple times to get the status of a process. + * + * The exit code will be the exit code of the process if it terminates + * normally, a negative signal if it terminated due to a signal, or -255 + * otherwise. It will not be changed if the process is still running. + * + * If you create a process with standard output piped to the application + * (`pipe_stdio` being true) then you should read all of the process output + * before calling SDL_WaitProcess(). If you don't do this the process might be + * blocked indefinitely waiting for output to be read and SDL_WaitProcess() + * will never return true; + * + * \param process The process to wait for. + * \param block If true, block until the process finishes; otherwise, report + * on the process' status. + * \param exitcode a Pointer filled in with the process exit code if the + * process has exited, may be nil. + * \returns true if the process exited, false otherwise. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_KillProcess + * \sa SDL_DestroyProcess + } +function SDL_WaitProcess(process: PSDL_Process; block: cbool; exitcode: pcint): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WaitProcess' {$ENDIF} {$ENDIF}; + +{* + * Destroy a previously created process object. + * + * Note that this does not stop the process, just destroys the SDL object used + * to track it. If you want to stop the process you should use + * SDL_KillProcess(). + * + * \param process The process object to destroy. + * + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CreateProcess + * \sa SDL_CreateProcessWithProperties + * \sa SDL_KillProcess + } +procedure SDL_DestroyProcess(process: PSDL_Process); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DestroyProcess' {$ENDIF} {$ENDIF}; + From 49f7147bc39dcd1523f0f3c39e3d209486d00aec Mon Sep 17 00:00:00 2001 From: Matthias Date: Mon, 10 Feb 2025 00:30:00 +0100 Subject: [PATCH 18/18] Add SDL_storage.inc --- units/SDL3.pas | 1 + units/SDL_storage.inc | 648 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 649 insertions(+) create mode 100644 units/SDL_storage.inc diff --git a/units/SDL3.pas b/units/SDL3.pas index 27b8ba4..e362ac2 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -124,6 +124,7 @@ interface {$I SDL_vulkan.inc} // 3.2.0 {$I SDL_thread.inc} // 3.2.0 {$I SDL_process.inc} // 3.2.0 +{$I SDL_storage.inc} // 3.2.0 diff --git a/units/SDL_storage.inc b/units/SDL_storage.inc new file mode 100644 index 0000000..3030195 --- /dev/null +++ b/units/SDL_storage.inc @@ -0,0 +1,648 @@ +{ + This file is part of: + + SDL3 for Pascal + (https://github.com/PascalGameDevelopment/SDL3-for-Pascal) + SPDX-License-Identifier: Zlib +} + +{* + * # CategoryStorage + * + * The storage API is a high-level API designed to abstract away the + * portability issues that come up when using something lower-level (in SDL's + * case, this sits on top of the [Filesystem](CategoryFilesystem) and + * [IOStream](CategoryIOStream) subsystems). It is significantly more + * restrictive than a typical filesystem API, for a number of reasons: + * + * 1. **What to Access:** A common pitfall with existing filesystem APIs is + * the assumption that all storage is monolithic. However, many other + * platforms (game consoles in particular) are more strict about what _type_ + * of filesystem is being accessed; for example, game content and user data + * are usually two separate storage devices with entirely different + * characteristics (and possibly different low-level APIs altogether!). + * + * 2. **How to Access:** Another common mistake is applications assuming that + * all storage is universally writeable - again, many platforms treat game + * content and user data as two separate storage devices, and only user data + * is writeable while game content is read-only. + * + * 3. **When to Access:** The most common portability issue with filesystem + * access is _timing_ - you cannot always assume that the storage device is + * always accessible all of the time, nor can you assume that there are no + * limits to how long you have access to a particular device. + * + * Consider the following example: + * + * ```c + * void ReadGameData(void) + * + * extern char** fileNames; + * extern size_t numFiles; + * for (size_t i = 0; i < numFiles; i += 1) + * FILE *data = fopen(fileNames[i], "rwb"); + * if (data == nil) + * // Something bad happened! + * else + * // A bunch of stuff happens here + * fclose(data); + * + * + * + * + * void ReadSave(void) + * + * FILE *save = fopen("saves/save0.sav", "rb"); + * if (save == nil) + * // Something bad happened! + * else + * // A bunch of stuff happens here + * fclose(save); + * + * + * + * void WriteSave(void) + * + * FILE *save = fopen("saves/save0.sav", "wb"); + * if (save == nil) + * // Something bad happened! + * else + * // A bunch of stuff happens here + * fclose(save); + * + * + * ``` + * + * Going over the bullet points again: + * + * 1. **What to Access:** This code accesses a global filesystem; game data + * and saves are all presumed to be in the current working directory (which + * may or may not be the game's installation folder!). + * + * 2. **How to Access:** This code assumes that content paths are writeable, + * and that save data is also writeable despite being in the same location as + * the game data. + * + * 3. **When to Access:** This code assumes that they can be called at any + * time, since the filesystem is always accessible and has no limits on how + * long the filesystem is being accessed. + * + * Due to these assumptions, the filesystem code is not portable and will fail + * under these common scenarios: + * + * - The game is installed on a device that is read-only, both content loading + * and game saves will fail or crash outright + * - Game/User storage is not implicitly mounted, so no files will be found + * for either scenario when a platform requires explicitly mounting + * filesystems + * - Save data may not be safe since the I/O is not being flushed or + * validated, so an error occurring elsewhere in the program may result in + * missing/corrupted save data + * + * When using SDL_Storage, these types of problems are virtually impossible to + * trip over: + * + * ```c + * void ReadGameData(void) + * + * extern char** fileNames; + * extern size_t numFiles; + * + * SDL_Storage *title = SDL_OpenTitleStorage(nil, 0); + * if (title == nil) + * // Something bad happened! + * + * while (!SDL_StorageReady(title)) + * SDL_Delay(1); + * + * + * for (size_t i = 0; i < numFiles; i += 1) + * void* dst; + * Uint64 dstLen = 0; + * + * if (SDL_GetStorageFileSize(title, fileNames[i], &dstLen) && dstLen > 0) + * dst = SDL_malloc(dstLen); + * if (SDL_ReadStorageFile(title, fileNames[i], dst, dstLen)) + * // A bunch of stuff happens here + * else + * // Something bad happened! + * + * SDL_free(dst); + * else + * // Something bad happened! + * + * + * + * SDL_CloseStorage(title); + * + * + * void ReadSave(void) + * + * SDL_Storage *user = SDL_OpenUserStorage("libsdl", "Storage Example", 0); + * if (user == nil) + * // Something bad happened! + * + * while (!SDL_StorageReady(user)) + * SDL_Delay(1); + * + * + * Uint64 saveLen = 0; + * if (SDL_GetStorageFileSize(user, "save0.sav", &saveLen) && saveLen > 0) + * void* dst = SDL_malloc(saveLen); + * if (SDL_ReadStorageFile(user, "save0.sav", dst, saveLen)) + * // A bunch of stuff happens here + * else + * // Something bad happened! + * + * SDL_free(dst); + * else + * // Something bad happened! + * + * + * SDL_CloseStorage(user); + * + * + * void WriteSave(void) + * + * SDL_Storage *user = SDL_OpenUserStorage("libsdl", "Storage Example", 0); + * if (user == nil) + * // Something bad happened! + * + * while (!SDL_StorageReady(user)) + * SDL_Delay(1); + * + * + * extern void *saveData; // A bunch of stuff happened here... + * extern Uint64 saveLen; + * if (!SDL_WriteStorageFile(user, "save0.sav", saveData, saveLen)) + * // Something bad happened! + * + * + * SDL_CloseStorage(user); + * + * ``` + * + * Note the improvements that SDL_Storage makes: + * + * 1. **What to Access:** This code explicitly reads from a title or user + * storage device based on the context of the function. + * + * 2. **How to Access:** This code explicitly uses either a read or write + * function based on the context of the function. + * + * 3. **When to Access:** This code explicitly opens the device when it needs + * to, and closes it when it is finished working with the filesystem. + * + * The result is an application that is significantly more robust against the + * increasing demands of platforms and their filesystems! + * + * A publicly available example of an SDL_Storage backend is the + * [Steam Cloud](https://partner.steamgames.com/doc/features/cloud) + * backend - you can initialize Steamworks when starting the program, and then + * SDL will recognize that Steamworks is initialized and automatically use + * ISteamRemoteStorage when the application opens user storage. More + * importantly, when you _open_ storage it knows to begin a "batch" of + * filesystem operations, and when you _close_ storage it knows to end and + * flush the batch. This is used by Steam to support + * [Dynamic Cloud Sync](https://steamcommunity.com/groups/steamworks/announcements/detail/3142949576401813670) + * ; users can save data on one PC, put the device to sleep, and then continue + * playing on another PC (and vice versa) with the save data fully + * synchronized across all devices, allowing for a seamless experience without + * having to do full restarts of the program. + * + * ## Notes on valid paths + * + * All paths in the Storage API use Unix-style path separators ('/'). Using a + * different path separator will not work, even if the underlying platform + * would otherwise accept it. This is to keep code using the Storage API + * portable between platforms and Storage implementations and simplify app + * code. + * + * Paths with relative directories ("." and "..") are forbidden by the Storage + * API. + * + * All valid UTF-8 strings (discounting the nil terminator character and the + * '/' path separator) are usable for filenames, however, an underlying + * Storage implementation may not support particularly strange sequences and + * refuse to create files with those names, etc. + } + +{* + * Function interface for SDL_Storage. + * + * Apps that want to supply a custom implementation of SDL_Storage will fill + * in all the functions in this struct, and then pass it to SDL_OpenStorage to + * create a custom SDL_Storage object. + * + * It is not usually necessary to do this; SDL provides standard + * implementations for many things you might expect to do with an SDL_Storage. + * + * This structure should be initialized using SDL_INIT_INTERFACE() + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_INIT_INTERFACE + } +type + PPSDL_StorageInterface = ^PSDL_StorageInterface; + PSDL_StorageInterface = ^TSDL_StorageInterface; + TSDL_StorageInterface = record + version: cuint32; { The version of this interface } + close: function(userdata: Pointer): cbool; cdecl; { Called when the storage is closed } + ready: function(userdata: Pointer): cbool; cdecl; { Optional, returns whether the storage is currently ready for access } + enumerate: function(userdata: Pointer; path: PAnsiChar; callback: TSDL_EnumerateDirectoryCallback; { Enumerate a directory, optional for write-only storage } + callback_userdata: Pointer): cbool; cdecl; + info: function(userdata: Pointer; path: PAnsiChar; info: PSDL_PathInfo): cbool; cdecl; { Get path information, optional for write-only storage } + read_file: function(userdata: Pointer; path: PAnsiChar; destination: Pointer; length: cuint64): cbool; cdecl; { Read a file from storage, optional for write-only storage } + write_file: function(userdata: Pointer; path: PAnsiChar; source: Pointer; length: cuint64): cbool; cdecl; { Write a file to storage, optional for read-only storage } + mkdir: function(userdata: Pointer; path: PAnsiChar): cbool; cdecl; { Create a directory, optional for read-only storage } + remove: function(userdata: Pointer; path: PAnsiChar): cbool; cdecl; { Remove a file or empty directory, optional for read-only storage } + rename: function(userdata: Pointer; oldpath: PAnsiChar; newpath: PAnsiChar): cbool; cdecl; { Rename a path, optional for read-only storage } + copy: function(userdata: Pointer; oldpath: PAnsiChar; newpath: PAnsiChar): cbool; cdecl; { Copy a file, optional for read-only storage } + space_remaining: function(userdata: Pointer): cuint64; cdecl; { Get the space remaining, optional for read-only storage } + end; + +{ 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. + } +{ #todo : SDL3-for-Pascal: Implement + +C: +SDL_COMPILE_TIME_ASSERT(SDL_StorageInterface_SIZE, + (sizeof(void *) == 4 && sizeof(SDL_StorageInterface) == 48) || + (sizeof(void *) == 8 && sizeof(SDL_StorageInterface) == 96)); } + +{* + * An abstract interface for filesystem access. + * + * This is an opaque datatype. One can create this object using standard SDL + * functions like SDL_OpenTitleStorage or SDL_OpenUserStorage, etc, or create + * an object with a custom implementation using SDL_OpenStorage. + * + * \since This struct is available since SDL 3.2.0. + } +type + PPSDL_Storage = ^PSDL_Storage; + PSDL_Storage = type Pointer; + +{* + * Opens up a read-only container for the application's filesystem. + * + * \param override a path to override the backend's default title root. + * \param props a property list that may contain backend-specific information. + * \returns a title storage container on success or nil on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseStorage + * \sa SDL_GetStorageFileSize + * \sa SDL_OpenUserStorage + * \sa SDL_ReadStorageFile + } +function SDL_OpenTitleStorage(override: PAnsiChar; props: TSDL_PropertiesID): PSDL_Storage; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_OpenTitleStorage' {$ENDIF} {$ENDIF}; + +{* + * Opens up a container for a user's unique read/write filesystem. + * + * While title storage can generally be kept open throughout runtime, user + * storage should only be opened when the client is ready to read/write files. + * This allows the backend to properly batch file operations and flush them + * when the container has been closed; ensuring safe and optimal save I/O. + * + * \param org the name of your organization. + * \param app the name of your application. + * \param props a property list that may contain backend-specific information. + * \returns a user storage container on success or nil on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseStorage + * \sa SDL_GetStorageFileSize + * \sa SDL_GetStorageSpaceRemaining + * \sa SDL_OpenTitleStorage + * \sa SDL_ReadStorageFile + * \sa SDL_StorageReady + * \sa SDL_WriteStorageFile + } +function SDL_OpenUserStorage(org: PAnsiChar; app: PAnsiChar; props: TSDL_PropertiesID): PSDL_Storage; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_OpenUserStorage' {$ENDIF} {$ENDIF}; + +{* + * Opens up a container for local filesystem storage. + * + * This is provided for development and tools. Portable applications should + * use SDL_OpenTitleStorage() for access to game data and + * SDL_OpenUserStorage() for access to user data. + * + * \param path the base path prepended to all storage paths, or nil for no + * base path. + * \returns a filesystem storage container on success or nil on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseStorage + * \sa SDL_GetStorageFileSize + * \sa SDL_GetStorageSpaceRemaining + * \sa SDL_OpenTitleStorage + * \sa SDL_OpenUserStorage + * \sa SDL_ReadStorageFile + * \sa SDL_WriteStorageFile + } +function SDL_OpenFileStorage(path: PAnsiChar): PSDL_Storage; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_OpenFileStorage' {$ENDIF} {$ENDIF}; + +{* + * Opens up a container using a client-provided storage interface. + * + * Applications do not need to use this function unless they are providing + * their own SDL_Storage implementation. If you just need an SDL_Storage, you + * should use the built-in implementations in SDL, like SDL_OpenTitleStorage() + * or SDL_OpenUserStorage(). + * + * This function makes a copy of `iface` and the caller does not need to keep + * it around after this call. + * + * \param iface the interface that implements this storage, initialized using + * SDL_INIT_INTERFACE(). + * \param userdata the Pointer that will be passed to the interface functions. + * \returns a storage container on success or nil on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_CloseStorage + * \sa SDL_GetStorageFileSize + * \sa SDL_GetStorageSpaceRemaining + * \sa SDL_INIT_INTERFACE + * \sa SDL_ReadStorageFile + * \sa SDL_StorageReady + * \sa SDL_WriteStorageFile + } +function SDL_OpenStorage(iface: PSDL_StorageInterface; userdata: Pointer): PSDL_Storage; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_OpenStorage' {$ENDIF} {$ENDIF}; + +{* + * Closes and frees a storage container. + * + * \param storage a storage container to close. + * \returns true if the container was freed with no errors, false otherwise; + * call SDL_GetError() for more information. Even if the function + * returns an error, the container data will be freed; the error is + * only for informational purposes. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_OpenFileStorage + * \sa SDL_OpenStorage + * \sa SDL_OpenTitleStorage + * \sa SDL_OpenUserStorage + } +function SDL_CloseStorage(storage: PSDL_Storage): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CloseStorage' {$ENDIF} {$ENDIF}; + +{* + * Checks if the storage container is ready to use. + * + * This function should be called in regular intervals until it returns true - + * however, it is not recommended to spinwait on this call, as the backend may + * depend on a synchronous message loop. + * + * \param storage a storage container to query. + * \returns true if the container is ready, false otherwise. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_StorageReady(storage: PSDL_Storage): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_StorageReady' {$ENDIF} {$ENDIF}; + +{* + * Query the size of a file within a storage container. + * + * \param storage a storage container to query. + * \param path the relative path of the file to query. + * \param length a Pointer to be filled with the file's length. + * \returns true if the file could be queried or false on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_ReadStorageFile + * \sa SDL_StorageReady + } +function SDL_GetStorageFileSize(storage: PSDL_Storage; path: PAnsiChar; length: pcuint64): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetStorageFileSize' {$ENDIF} {$ENDIF}; + +{* + * Synchronously read a file from a storage container into a client-provided + * buffer. + * + * The value of `length` must match the length of the file exactly; call + * SDL_GetStorageFileSize() to get this value. This behavior may be relaxed in + * a future release. + * + * \param storage a storage container to read from. + * \param path the relative path of the file to read. + * \param destination a client-provided buffer to read the file into. + * \param length the length of the destination buffer. + * \returns true if the file was read or false on failure; call SDL_GetError() + * for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetStorageFileSize + * \sa SDL_StorageReady + * \sa SDL_WriteStorageFile + } +function SDL_ReadStorageFile(storage: PSDL_Storage; path: PAnsiChar; destination: Pointer; length: cuint64): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadStorageFile' {$ENDIF} {$ENDIF}; + +{* + * Synchronously write a file from client memory into a storage container. + * + * \param storage a storage container to write to. + * \param path the relative path of the file to write. + * \param source a client-provided buffer to write from. + * \param length the length of the source buffer. + * \returns true if the file was written or false on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetStorageSpaceRemaining + * \sa SDL_ReadStorageFile + * \sa SDL_StorageReady + } +function SDL_WriteStorageFile(storage: PSDL_Storage; path: PAnsiChar; source: Pointer; length: cuint64): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteStorageFile' {$ENDIF} {$ENDIF}; + +{* + * Create a directory in a writable storage container. + * + * \param storage a storage container. + * \param path the path of the directory to create. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StorageReady + } +function SDL_CreateStorageDirectory(storage: PSDL_Storage; path: PAnsiChar): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateStorageDirectory' {$ENDIF} {$ENDIF}; + +{* + * Enumerate a directory in a storage container through a callback function. + * + * This function provides every directory entry through an app-provided + * callback, called once for each directory entry, until all results have been + * provided or the callback returns either SDL_ENUM_SUCCESS or + * SDL_ENUM_FAILURE. + * + * This will return false if there was a system problem in general, or if a + * callback returns SDL_ENUM_FAILURE. A successful return means a callback + * returned SDL_ENUM_SUCCESS to halt enumeration, or all directory entries + * were enumerated. + * + * If `path` is nil, this is treated as a request to enumerate the root of + * the storage container's tree. An empty string also works for this. + * + * \param storage a storage container. + * \param path the path of the directory to enumerate, or nil for the root. + * \param callback a function that is called for each entry in the directory. + * \param userdata a Pointer that is passed to `callback`. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StorageReady + } +function SDL_EnumerateStorageDirectory(storage: PSDL_Storage; path: PAnsiChar; callback: TSDL_EnumerateDirectoryCallback; userdata: Pointer): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_EnumerateStorageDirectory' {$ENDIF} {$ENDIF}; + +{* + * Remove a file or an empty directory in a writable storage container. + * + * \param storage a storage container. + * \param path the path of the directory to enumerate. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StorageReady + } +function SDL_RemoveStoragePath(storage: PSDL_Storage; path: PAnsiChar): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RemoveStoragePath' {$ENDIF} {$ENDIF}; + +{* + * Rename a file or directory in a writable storage container. + * + * \param storage a storage container. + * \param oldpath the old path. + * \param newpath the new path. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StorageReady + } +function SDL_RenameStoragePath(storage: PSDL_Storage; oldpath: PAnsiChar; newpath: PAnsiChar): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RenameStoragePath' {$ENDIF} {$ENDIF}; + +{* + * Copy a file in a writable storage container. + * + * \param storage a storage container. + * \param oldpath the old path. + * \param newpath the new path. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StorageReady + } +function SDL_CopyStorageFile(storage: PSDL_Storage; oldpath: PAnsiChar; newpath: PAnsiChar): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CopyStorageFile' {$ENDIF} {$ENDIF}; + +{* + * Get information about a filesystem path in a storage container. + * + * \param storage a storage container. + * \param path the path to query. + * \param info a Pointer filled in with information about the path, or nil to + * check for the existence of a file. + * \returns true on success or false if the file doesn't exist, or another + * failure; call SDL_GetError() for more information. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StorageReady + } +function SDL_GetStoragePathInfo(storage: PSDL_Storage; path: PAnsiChar; info: PSDL_PathInfo): cbool; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetStoragePathInfo' {$ENDIF} {$ENDIF}; + +{* + * Queries the remaining space in a storage container. + * + * \param storage a storage container to query. + * \returns the amount of remaining space, in bytes. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_StorageReady + * \sa SDL_WriteStorageFile + } +function SDL_GetStorageSpaceRemaining(storage: PSDL_Storage): cuint64; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetStorageSpaceRemaining' {$ENDIF} {$ENDIF}; + +{* + * Enumerate a directory tree, filtered by pattern, and return a list. + * + * Files are filtered out if they don't match the string in `pattern`, which + * may contain wildcard characters '*' (match everything) and '?' (match one + * character). If pattern is nil, no filtering is done and all results are + * returned. Subdirectories are permitted, and are specified with a path + * separator of '/'. Wildcard characters '*' and '?' never match a path + * separator. + * + * `flags` may be set to SDL_GLOB_CASEINSENSITIVE to make the pattern matching + * case-insensitive. + * + * The returned array is always nil-terminated, for your iterating + * convenience, but if `count` is non-nil, on return it will contain the + * number of items in the array, not counting the nil terminator. + * + * If `path` is nil, this is treated as a request to enumerate the root of + * the storage container's tree. An empty string also works for this. + * + * \param storage a storage container. + * \param path the path of the directory to enumerate, or nil for the root. + * \param pattern the pattern that files in the directory must match. Can be + * nil. + * \param flags `SDL_GLOB_*` bitflags that affect this search. + * \param count on return, will be set to the number of items in the returned + * array. Can be nil. + * \returns an array of strings on success or nil on failure; call + * SDL_GetError() for more information. The caller should pass the + * returned Pointer to SDL_free when done with it. This is a single + * allocation that should be freed with SDL_free() when it is no + * longer needed. + * + * \threadsafety It is safe to call this function from any thread, assuming + * the `storage` object is thread-safe. + * + * \since This function is available since SDL 3.2.0. + } +function SDL_GlobStorageDirectory(storage: PSDL_Storage; path: PAnsiChar; pattern: PAnsiChar; flags: TSDL_GlobFlags; count: pcint):PPAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GlobStorageDirectory' {$ENDIF} {$ENDIF}; +