From 20eb3d3419e30d4ec457241dda98a39f1b7eaa79 Mon Sep 17 00:00:00 2001 From: suve Date: Thu, 14 Aug 2025 17:12:31 +0200 Subject: [PATCH 1/7] Update SDL_init.inc to match SDL 3.2.20 --- units/SDL3.pas | 2 +- units/SDL_init.inc | 154 ++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 141 insertions(+), 15 deletions(-) diff --git a/units/SDL3.pas b/units/SDL3.pas index 62f9d6c..c28a242 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -76,7 +76,6 @@ interface corresponding C header file. Inc file was updated against SDL_init.inc --> SDL_init.h this version of the header file: } -{$I SDL_init.inc} // 3.1.6-prev {$I SDL_log.inc} // 3.1.6-prev {$I SDL_version.inc} // 3.1.6-prev {$I SDL_revision.inc} // 3.1.6-prev @@ -111,6 +110,7 @@ interface {$I SDL_touch.inc} // 3.1.6-prev {$I SDL_camera.inc} // 3.1.6-prev {$I SDL_events.inc} // 3.1.6-prev +{$I SDL_init.inc} // 3.2.20 {$I SDL_render.inc} // 3.1.6-prev {$I SDL_gpu.inc} // 3.2.0 {$I SDL_clipboard.inc} // 3.2.0 diff --git a/units/SDL_init.inc b/units/SDL_init.inc index ebfb6ca..e5a6289 100644 --- a/units/SDL_init.inc +++ b/units/SDL_init.inc @@ -41,7 +41,7 @@ * These are the flags which may be passed to SDL_Init(). You should specify * the subsystems which you will be using in your application. * - * \since This datatype is available since SDL 3.1.3. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_Quit @@ -56,8 +56,8 @@ type const SDL_INIT_AUDIO = TSDL_InitFlags($00000010); { `SDL_INIT_AUDIO` implies `SDL_INIT_EVENTS` } - SDL_INIT_VIDEO = TSDL_InitFlags($00000020); { `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS` } - SDL_INIT_JOYSTICK = TSDL_InitFlags($00000200); { `SDL_INIT_JOYSTICK` implies `SDL_INIT_EVENTS`, should be initialized on the same thread as SDL_INIT_VIDEO on Windows if you don't set SDL_HINT_JOYSTICK_THREAD } + SDL_INIT_VIDEO = TSDL_InitFlags($00000020); { `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS`, should be initialized on the main thread } + SDL_INIT_JOYSTICK = TSDL_InitFlags($00000200); { `SDL_INIT_JOYSTICK` implies `SDL_INIT_EVENTS` } SDL_INIT_HAPTIC = TSDL_InitFlags($00001000); SDL_INIT_GAMEPAD = TSDL_InitFlags($00002000); { `SDL_INIT_GAMEPAD` implies `SDL_INIT_JOYSTICK` } SDL_INIT_EVENTS = TSDL_InitFlags($00004000); @@ -82,7 +82,7 @@ const * [Main callbacks in SDL3](https://wiki.libsdl.org/SDL3/README/main-functions#main-callbacks-in-sdl3) * for complete details. * - * \since This enum is available since SDL 3.1.3. + * \since This enum is available since SDL 3.2.0. } type PPSDL_AppResult = ^PSDL_AppResult; @@ -94,9 +94,68 @@ const SDL_APP_FAILURE = 2; {*< Value that requests termination with error from the main callbacks. } type +{* + * Function pointer typedef for SDL_AppInit. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppInit directly. + * + * \param appstate a place where the app can optionally store a pointer for + * future use. + * \param argc the standard ANSI C main's argc; number of elements in `argv`. + * \param argv the standard ANSI C main's argv; array of command line + * arguments. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + *} TSDL_AppInit_func = function(appstate: PPointer; argc: cint; argv: PPAnsiChar): TSDL_AppResult; cdecl; + +{** + * Function pointer typedef for SDL_AppIterate. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppIterate directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + *} TSDL_AppIterate_func = function(appstate: Pointer): TSDL_AppResult; cdecl; - //TSDL_AppEvent_func = function(appstate: Pointer; event: PSDL_Event): TSDL_AppResult; cdecl; // uncomment after EVENT translation + +{** + * Function pointer typedef for SDL_AppEvent. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppEvent directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \param event the new event for the app to examine. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.2.0. + *} + TSDL_AppEvent_func = function(appstate: Pointer; event: PSDL_Event): TSDL_AppResult; cdecl; + +{** + * Function pointer typedef for SDL_AppQuit. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to + * use this should just implement SDL_AppEvent directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \param result the result code that terminated the app (success or failure). + * + * \since This datatype is available since SDL 3.2.0. + *} TSDL_AppQuit_func = procedure(appstate: Pointer; result: TSDL_AppResult); cdecl; {* @@ -120,7 +179,7 @@ type * - `SDL_INIT_AUDIO`: audio subsystem; automatically initializes the events * subsystem * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events - * subsystem + * subsystem, should be initialized on the main thread. * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the * events subsystem * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem @@ -145,7 +204,7 @@ type * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadata * \sa SDL_SetAppMetadataProperty @@ -167,7 +226,7 @@ function SDL_Init(flags: TSDL_InitFlags): Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_Quit @@ -184,7 +243,7 @@ function SDL_InitSubSystem(flags: TSDL_InitFlags): Boolean; cdecl; * * \param flags any of the flags used by SDL_Init(); see SDL_Init for details. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_InitSubSystem * \sa SDL_Quit @@ -199,7 +258,7 @@ procedure SDL_QuitSubSystem(flags: TSDL_InitFlags); cdecl; * \returns a mask of all initialized subsystems if `flags` is 0, otherwise it * returns the initialization status of the specified subsystems. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_Init * \sa SDL_InitSubSystem @@ -226,6 +285,73 @@ function SDL_WasInit(flags: TSDL_InitFlags): TSDL_InitFlags; cdecl; procedure SDL_Quit; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_Quit' {$ENDIF} {$ENDIF}; +{** + * Return whether this is the main thread. + * + * On Apple platforms, the main thread is the thread that runs your program's + * main() entry point. On other platforms, the main thread is the one that + * calls SDL_Init(SDL_INIT_VIDEO), which should usually be the one that runs + * your program's main() entry point. If you are using the main callbacks, + * SDL_AppInit(), SDL_AppIterate(), and SDL_AppQuit() are all called on the + * main thread. + * + * \returns true if this thread is the main thread, or false otherwise. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_RunOnMainThread + *} +function SDL_IsMainThread(): Boolean; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_IsMainThread' {$ENDIF} {$ENDIF}; + +type + PPSDL_MainThreadCallback = ^PSDL_MainThreadCallback; + PSDL_MainThreadCallback = ^TSDL_MainThreadCallback; + + {** + * Callback run on the main thread. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_RunOnMainThread + *} + TSDL_MainThreadCallback = procedure(userdata: Pointer); cdecl; + +{** + * Call a function on the main thread during event processing. + * + * If this is called on the main thread, the callback is executed immediately. + * If this is called on another thread, this callback is queued for execution + * on the main thread during event processing. + * + * Be careful of deadlocks when using this functionality. You should not have + * the main thread wait for the current thread while this function is being + * called with `wait_complete` true. + * + * \param callback the callback to call on the main thread. + * \param userdata a pointer that is passed to `callback`. + * \param wait_complete true to wait for the callback to complete, false to + * return immediately. + * \returns true on success or false on failure; call SDL_GetError() for more + * information. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_IsMainThread + *} +function SDL_RunOnMainThread( + callback: TSDL_MainThreadCallback; + userdata: Pointer; + wait_complete: Boolean +): Boolean; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RunOnMainThread' {$ENDIF} {$ENDIF}; + {* * Specify basic metadata about your app. * @@ -258,7 +384,7 @@ procedure SDL_Quit; cdecl; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadataProperty } @@ -280,7 +406,7 @@ function SDL_SetAppMetadata(appname: PAnsiChar; appversion: PAnsiChar; appidenti * Multiple calls to this function are allowed, but various state might not * change once it has been set up with a previous call to this function. * - * Once set, this metadata can be read using SDL_GetMetadataProperty(). + * Once set, this metadata can be read using SDL_GetAppMetadataProperty(). * * These are the supported properties: * @@ -321,7 +447,7 @@ function SDL_SetAppMetadata(appname: PAnsiChar; appversion: PAnsiChar; appidenti * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetAppMetadataProperty * \sa SDL_SetAppMetadata @@ -354,7 +480,7 @@ const * freed if you call SDL_SetAppMetadataProperty() to set that * property from another thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetAppMetadata * \sa SDL_SetAppMetadataProperty From fed0b630397811fedef1b63fff5f880bf025eada Mon Sep 17 00:00:00 2001 From: suve Date: Thu, 14 Aug 2025 17:44:33 +0200 Subject: [PATCH 2/7] Update SDL_surface.inc to match SDL 3.2.20 --- units/SDL3.pas | 8 +- units/SDL_surface.inc | 324 ++++++++++++++++++++++++++++-------------- 2 files changed, 221 insertions(+), 111 deletions(-) diff --git a/units/SDL3.pas b/units/SDL3.pas index c28a242..4c1c4da 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -92,7 +92,7 @@ interface {$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_surface.inc} // 3.2.20 {$I SDL_video.inc} // 3.1.6-prev {$I SDL_timer.inc} // 3.1.6-prev {$I SDL_error.inc} // 3.1.6-prev @@ -311,6 +311,12 @@ function SDL_SCANCODE_TO_KEYCODE(X: TSDL_Scancode): TSDL_Keycode; Result:=X or SDLK_SCANCODE_MASK; end; +{ Macros from SDL_surface.h } +function SDL_MUSTLOCK(Const S: PSDL_Surface): Boolean; +begin + Result:=(S^.flags and SDL_SURFACE_LOCK_NEEDED)=SDL_SURFACE_LOCK_NEEDED; +end; + { Macros from SDL_video.h } function SDL_WINDOWPOS_UNDEFINED_DISPLAY(X: Integer): Integer; begin diff --git a/units/SDL_surface.inc b/units/SDL_surface.inc index d22e3ae..f8d272d 100644 --- a/units/SDL_surface.inc +++ b/units/SDL_surface.inc @@ -18,8 +18,7 @@ * * There is also a simple .bmp loader, SDL_LoadBMP(). SDL itself does not * provide loaders for various other file formats, but there are several - * excellent - external libraries that do, including it's own satellite library, + * excellent external libraries that do, including its own satellite library, * SDL_image: * * https://github.com/libsdl-org/SDL_image @@ -30,7 +29,7 @@ * * These are generally considered read-only. * - * \since This datatype is available since SDL 3.1.3. + * \since This datatype is available since SDL 3.2.0. } type PPSDL_SurfaceFlags = ^PSDL_SurfaceFlags; @@ -43,38 +42,24 @@ const SDL_SURFACE_LOCKED = TSDL_SurfaceFlags($00000004); {*< Surface is currently locked } SDL_SURFACE_SIMD_ALIGNED = TSDL_SurfaceFlags($00000008); {*< Surface uses pixel memory allocated with SDL_aligned_alloc() } -{* - * Evaluates to true if the surface needs to be locked before access. - * - * \since This macro is available since SDL 3.1.3. - } -{ #todo : SDL3 for Pascal: translate macro } -// #define SDL_MUSTLOCK(S) ((((S)->flags & SDL_SURFACE_LOCK_NEEDED)) == SDL_SURFACE_LOCK_NEEDED) -// function SDL_MUSTLOCK(S: Integer): Integer; -{ -function SDL_MUSTLOCK(S: PSDL_Surface): Boolean; -begin - Result:=(S^.flags and SDL_SURFACE_LOCK_NEEDED)=SDL_SURFACE_LOCK_NEEDED; -end; - } - {* * The scaling mode. * - * \since This enum is available since SDL 3.1.3. + * \since This enum is available since SDL 3.2.0. } type PPSDL_ScaleMode = ^PSDL_ScaleMode; PSDL_ScaleMode = ^TSDL_ScaleMode; TSDL_ScaleMode = type Integer; const + SDL_SCALEMODE_INVALID = TSDL_ScaleMode(-1); SDL_SCALEMODE_NEAREST = TSDL_ScaleMode(0); {*< nearest pixel sampling } SDL_SCALEMODE_LINEAR = TSDL_ScaleMode(1); {*< linear filtering } {* * The flip mode. * - * \since This enum is available since SDL 3.1.3. + * \since This enum is available since SDL 3.2.0. } type PPSDL_FlipMode = ^PSDL_FlipMode; @@ -100,7 +85,15 @@ const * remaining bytes to reach the pitch are used as padding to reach a desired * alignment, and have undefined contents. * - * \since This struct is available since SDL 3.1.3. + * When a surface holds YUV format data, the planes are assumed to be + * contiguous without padding between them, e.g. a 32x32 surface in NV12 + * format with a pitch of 32 would consist of 32x32 bytes of Y plane followed + * by 32x16 bytes of UV plane. + * + * When a surface holds MJPG format data, pixels points at the compressed JPEG + * image and pitch is the length of that data. + * + * \since This struct is available since SDL 3.2.0. * * \sa SDL_CreateSurface * \sa SDL_DestroySurface @@ -119,6 +112,13 @@ type reserved: Pointer; {*< Reserved for internal use } end; +{* + * Evaluates to true if the surface needs to be locked before access. + * + * \since This macro is available since SDL 3.2.0. + } +function SDL_MUSTLOCK(Const S: PSDL_Surface): Boolean; + {* * Allocate a new surface with a specific pixel format. * @@ -130,7 +130,9 @@ type * \returns the new SDL_Surface structure that is created or nil on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSurfaceFrom * \sa SDL_DestroySurface @@ -159,7 +161,9 @@ function SDL_CreateSurface(width: cint; height: cint; format: TSDL_PixelFormat): * \returns the new SDL_Surface structure that is created or nil on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateSurface * \sa SDL_DestroySurface @@ -174,9 +178,10 @@ function SDL_CreateSurfaceFrom(width: cint; height: cint; format: TSDL_PixelForm * * \param surface the SDL_Surface to free. * - * \since This function is available since SDL 3.1.3. + * \threadsafety No other thread should be using the surface when it is freed. + * + * \since This function is available since SDL 3.2.0. * - * \sa SDL_CreateStackSurface * \sa SDL_CreateSurface * \sa SDL_CreateSurfaceFrom } @@ -202,6 +207,10 @@ procedure SDL_DestroySurface(surface: PSDL_Surface); cdecl; * the same tone mapping that Chrome uses for HDR content, the form "*=N", * where N is a floating point scale factor applied in linear space, and * "none", which disables tone mapping. This defaults to "chrome". + * - `SDL_PROP_SURFACE_HOTSPOT_X_NUMBER`: the hotspot pixel offset from the + * left edge of the image, if this surface is being used as a cursor. + * - `SDL_PROP_SURFACE_HOTSPOT_Y_NUMBER`: the hotspot pixel offset from the + * top edge of the image, if this surface is being used as a cursor. * * \param surface the SDL_Surface structure to query. * \returns a valid property ID on success or 0 on failure; call @@ -216,6 +225,8 @@ const SDL_PROP_SURFACE_SDR_WHITE_POINT_FLOAT = 'SDL.surface.SDR_white_point'; SDL_PROP_SURFACE_HDR_HEADROOM_FLOAT = 'SDL.surface.HDR_headroom'; SDL_PROP_SURFACE_TONEMAP_OPERATOR_STRING = 'SDL.surface.tonemap'; + SDL_PROP_SURFACE_HOTSPOT_X_NUMBER = 'SDL.surface.hotspot.x'; + SDL_PROP_SURFACE_HOTSPOT_Y_NUMBER = 'SDL.surface.hotspot.y'; {* * Set the colorspace used by a surface. @@ -224,12 +235,14 @@ const * interpreted in color operations. * * \param surface the SDL_Surface structure to update. - * \param colorspace an SDL_ColorSpace value describing the surface + * \param colorspace an SDL_Colorspace value describing the surface * colorspace. * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorspace } @@ -248,7 +261,9 @@ function SDL_SetSurfaceColorspace(surface: PSDL_Surface; colorspace: TSDL_Colors * \returns the colorspace used by the surface, or SDL_COLORSPACE_UNKNOWN if * the surface is nil. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorspace } @@ -277,7 +292,9 @@ function SDL_GetSurfaceColorspace(surface: PSDL_Surface): TSDL_Colorspace; cdecl * the surface didn't have an index format); call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetPaletteColors } @@ -294,7 +311,9 @@ function SDL_CreateSurfacePalette(surface: PSDL_Surface): PSDL_Palette; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePalette * \sa SDL_GetSurfacePalette @@ -309,7 +328,9 @@ function SDL_SetSurfacePalette(surface: PSDL_Surface; palette: PSDL_Palette): Bo * \returns a Pointer to the palette used by the surface, or nil if there is * no palette used. * - * \since This function is available since SDL 3.1.3. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfacePalette } @@ -333,7 +354,9 @@ function SDL_GetSurfacePalette(surface: PSDL_Surface): PSDL_Palette; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_RemoveSurfaceAlternateImages * \sa SDL_GetSurfaceImages @@ -346,9 +369,11 @@ function SDL_AddSurfaceAlternateImage(surface: PSDL_Surface; image: PSDL_Surface * Return whether a surface has alternate versions available. * * \param surface the SDL_Surface structure to query. - * \returns true if alternate versions are available or true otherwise. + * \returns true if alternate versions are available or false otherwise. * - * \since This function is available since SDL 3.1.3. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_RemoveSurfaceAlternateImages @@ -374,7 +399,9 @@ function SDL_SurfaceHasAlternateImages(surface: PSDL_Surface): Boolean; cdecl; * 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.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_RemoveSurfaceAlternateImages @@ -391,7 +418,9 @@ function SDL_GetSurfaceImages(surface: PSDL_Surface; count: pcint): PPSDL_Surfac * * \param surface the SDL_Surface structure to update. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddSurfaceAlternateImage * \sa SDL_GetSurfaceImages @@ -416,7 +445,11 @@ procedure SDL_RemoveSurfaceAlternateImages(surface: PSDL_Surface); cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. The locking referred to by + * this function is making the pixels available for direct + * access, not thread-safe locking. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MUSTLOCK * \sa SDL_UnlockSurface @@ -429,7 +462,11 @@ function SDL_LockSurface(surface: PSDL_Surface): Boolean; cdecl; * * \param surface the SDL_Surface structure to be unlocked. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. The locking referred to by + * this function is making the pixels available for direct + * access, not thread-safe locking. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LockSurface } @@ -448,7 +485,9 @@ procedure SDL_UnlockSurface(surface: PSDL_Surface); cdecl; * \returns a Pointer to a new SDL_Surface structure or nil on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface * \sa SDL_LoadBMP @@ -467,7 +506,9 @@ function SDL_LoadBMP_IO(src: PSDL_IOStream; closeio: Boolean): PSDL_Surface; cde * \returns a Pointer to a new SDL_Surface structure or nil on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface * \sa SDL_LoadBMP_IO @@ -493,7 +534,9 @@ function SDL_LoadBMP(file_: PAnsiChar): PSDL_Surface; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadBMP_IO * \sa SDL_SaveBMP @@ -515,7 +558,9 @@ function SDL_SaveBMP_IO(surface: PSDL_Surface; dst: PSDL_IOStream; closeio: Bool * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_LoadBMP * \sa SDL_SaveBMP_IO @@ -535,7 +580,9 @@ function SDL_SaveBMP(surface: PSDL_Surface; file_: PAnsiChar): Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface * \sa SDL_LockSurface @@ -552,7 +599,9 @@ function SDL_SetSurfaceRLE(surface: PSDL_Surface; enabled: Boolean): Boolean; cd * \param surface the SDL_Surface structure to query. * \returns true if the surface is RLE enabled, false otherwise. * - * \since This function is available since SDL 3.1.3. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceRLE } @@ -575,7 +624,9 @@ function SDL_SurfaceHasRLE(surface: PSDL_Surface): Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorKey * \sa SDL_SetSurfaceRLE @@ -592,7 +643,9 @@ function SDL_SetSurfaceColorKey(surface: PSDL_Surface; enabled: Boolean; key: cu * \param surface the SDL_Surface structure to query. * \returns true if the surface has a color key, false otherwise. * - * \since This function is available since SDL 3.1.3. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorKey * \sa SDL_GetSurfaceColorKey @@ -613,7 +666,9 @@ function SDL_SurfaceHasColorKey(surface: PSDL_Surface): Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceColorKey * \sa SDL_SurfaceHasColorKey @@ -637,7 +692,9 @@ function SDL_GetSurfaceColorKey(surface: PSDL_Surface; key: pcuint32): Boolean; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorMod * \sa SDL_SetSurfaceAlphaMod @@ -655,7 +712,9 @@ function SDL_SetSurfaceColorMod(surface: PSDL_Surface; r: cuint8; g: cuint8; b: * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceAlphaMod * \sa SDL_SetSurfaceColorMod @@ -676,7 +735,9 @@ function SDL_GetSurfaceColorMod(surface: PSDL_Surface; r: pcuint8; g: pcuint8; b * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceAlphaMod * \sa SDL_SetSurfaceColorMod @@ -692,7 +753,9 @@ function SDL_SetSurfaceAlphaMod(surface: PSDL_Surface; alpha: cuint8): Boolean; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceColorMod * \sa SDL_SetSurfaceAlphaMod @@ -712,7 +775,9 @@ function SDL_GetSurfaceAlphaMod(surface: PSDL_Surface; alpha: pcuint8): Boolean; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceBlendMode } @@ -727,7 +792,9 @@ function SDL_SetSurfaceBlendMode(surface: PSDL_Surface; blendMode: TSDL_BlendMod * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceBlendMode } @@ -749,7 +816,9 @@ function SDL_GetSurfaceBlendMode(surface: PSDL_Surface; blendMode: PSDL_BlendMod * \returns true if the rectangle intersects the surface, otherwise false and * blits will be completely clipped. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetSurfaceClipRect } @@ -769,7 +838,9 @@ function SDL_SetSurfaceClipRect(surface: PSDL_Surface; rect: PSDL_Rect): Boolean * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetSurfaceClipRect } @@ -784,7 +855,9 @@ function SDL_GetSurfaceClipRect(surface: PSDL_Surface; rect: PSDL_Rect): Boolean * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. } function SDL_FlipSurface(surface: PSDL_Surface; flip: TSDL_FlipMode): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_FlipSurface' {$ENDIF} {$ENDIF}; @@ -801,7 +874,9 @@ function SDL_FlipSurface(surface: PSDL_Surface; flip: TSDL_FlipMode): Boolean; c * \returns a copy of the surface or nil on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface } @@ -821,7 +896,9 @@ function SDL_DuplicateSurface(surface: PSDL_Surface): PSDL_Surface; cdecl; * \returns a copy of the surface or nil on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroySurface } @@ -847,7 +924,9 @@ function SDL_ScaleSurface(surface: PSDL_Surface; width: cint; height: cint; scal * \returns the new SDL_Surface structure that is created or nil on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertSurfaceAndColorspace * \sa SDL_DestroySurface @@ -874,9 +953,10 @@ function SDL_ConvertSurface(surface: PSDL_Surface; format: TSDL_PixelFormat): PS * \returns the new SDL_Surface structure that is created or nil on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * - * \sa SDL_ConvertSurface * \sa SDL_ConvertSurface * \sa SDL_DestroySurface } @@ -894,10 +974,14 @@ function SDL_ConvertSurfaceAndColorspace(surface: PSDL_Surface; format: TSDL_Pix * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. * \param dst a Pointer to be filled in with new pixel data. * \param dst_pitch the pitch of the destination pixels, in bytes. - * \returns false on success or false on failure; call SDL_GetError() for more + * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety The same destination pixels should not be used from two + * threads at once. It is safe to use the same source pixels + * from multiple threads. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertPixelsAndColorspace } @@ -911,23 +995,27 @@ function SDL_ConvertPixels(width: cint; height: cint; src_format: TSDL_PixelForm * \param width the width of the block to copy, in pixels. * \param height the height of the block to copy, in pixels. * \param src_format an SDL_PixelFormat value of the `src` pixels format. - * \param src_colorspace an SDL_ColorSpace value describing the colorspace of + * \param src_colorspace an SDL_Colorspace value describing the colorspace of * the `src` pixels. * \param src_properties an SDL_PropertiesID with additional source color * properties, or 0. * \param src a Pointer to the source pixels. * \param src_pitch the pitch of the source pixels, in bytes. * \param dst_format an SDL_PixelFormat value of the `dst` pixels format. - * \param dst_colorspace an SDL_ColorSpace value describing the colorspace of + * \param dst_colorspace an SDL_Colorspace value describing the colorspace of * the `dst` pixels. * \param dst_properties an SDL_PropertiesID with additional destination color * properties, or 0. * \param dst a Pointer to be filled in with new pixel data. * \param dst_pitch the pitch of the destination pixels, in bytes. - * \returns false on success or false on failure; call SDL_GetError() for more + * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety The same destination pixels should not be used from two + * threads at once. It is safe to use the same source pixels + * from multiple threads. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ConvertPixels } @@ -952,7 +1040,11 @@ function SDL_ConvertPixelsAndColorspace(width: cint; height: cint; src_format: T * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety The same destination pixels should not be used from two + * threads at once. It is safe to use the same source pixels + * from multiple threads. + * + * \since This function is available since SDL 3.2.0. } function SDL_PremultiplyAlpha(width: cint; height: cint; src_format: TSDL_PixelFormat; src: Pointer; src_pitch: cint; dst_format: TSDL_PixelFormat; dst: Pointer; dst_pitch: cint; linear: Boolean): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_PremultiplyAlpha' {$ENDIF} {$ENDIF}; @@ -968,7 +1060,9 @@ function SDL_PremultiplyAlpha(width: cint; height: cint; src_format: TSDL_PixelF * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. } function SDL_PremultiplySurfaceAlpha(surface: PSDL_Surface; linear: Boolean): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_PremultiplySurfaceAlpha' {$ENDIF} {$ENDIF}; @@ -989,7 +1083,9 @@ function SDL_PremultiplySurfaceAlpha(surface: PSDL_Surface; linear: Boolean): Bo * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. } function SDL_ClearSurface(surface: PSDL_Surface; r: cfloat; g: cfloat; b: cfloat; a: cfloat): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ClearSurface' {$ENDIF} {$ENDIF}; @@ -1013,7 +1109,9 @@ function SDL_ClearSurface(surface: PSDL_Surface; r: cfloat; g: cfloat; b: cfloat * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_FillSurfaceRects } @@ -1039,7 +1137,9 @@ function SDL_FillSurfaceRect(dst: PSDL_Surface; rect: PSDL_Rect; color: cuint32) * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_FillSurfaceRect } @@ -1047,12 +1147,11 @@ function SDL_FillSurfaceRects(dst: PSDL_Surface; rects: PSDL_Rect; count: cint; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_FillSurfaceRects' {$ENDIF} {$ENDIF}; {* - * Performs a fast blit from the source surface to the destination surface. + * Performs a fast blit from the source surface to the destination surface + * with clipping. * - * This assumes that the source and destination rectangles are the same size. * If either `srcrect` or `dstrect` are nil, the entire surface (`src` or - * `dst`) is copied. The final blit rectangles are saved in `srcrect` and - * `dstrect` after all clipping is performed. + * `dst`) is copied while ensuring clipping to `dst->clip_rect`. * * The blit function should not be called on a locked surface. * @@ -1111,11 +1210,10 @@ function SDL_FillSurfaceRects(dst: PSDL_Surface; rects: PSDL_Rect; count: cint; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \threadsafety The same destination surface should not be used from two - * threads at once. It is safe to use the same source surface - * from multiple threads. + * \threadsafety Only one thread should be using the `src` and `dst` surfaces + * at any given time. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurfaceScaled } @@ -1137,11 +1235,10 @@ function SDL_BlitSurface(src: PSDL_Surface; srcrect: PSDL_Rect; dst: PSDL_Surfac * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \threadsafety The same destination surface should not be used from two - * threads at once. It is safe to use the same source surface - * from multiple threads. + * \threadsafety Only one thread should be using the `src` and `dst` surfaces + * at any given time. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface } @@ -1163,11 +1260,10 @@ function SDL_BlitSurfaceUnchecked(src: PSDL_Surface; srcrect: PSDL_Rect; dst: PS * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \threadsafety The same destination surface should not be used from two - * threads at once. It is safe to use the same source surface - * from multiple threads. + * \threadsafety Only one thread should be using the `src` and `dst` surfaces + * at any given time. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface } @@ -1190,11 +1286,10 @@ function SDL_BlitSurfaceScaled(src: PSDL_Surface; srcrect: PSDL_Rect; dst: PSDL_ * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \threadsafety The same destination surface should not be used from two - * threads at once. It is safe to use the same source surface - * from multiple threads. + * \threadsafety Only one thread should be using the `src` and `dst` surfaces + * at any given time. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurfaceScaled } @@ -1217,11 +1312,10 @@ function SDL_BlitSurfaceUncheckedScaled(src: PSDL_Surface; srcrect: PSDL_Rect; d * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \threadsafety The same destination surface should not be used from two - * threads at once. It is safe to use the same source surface - * from multiple threads. + * \threadsafety Only one thread should be using the `src` and `dst` surfaces + * at any given time. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface } @@ -1248,11 +1342,10 @@ function SDL_BlitSurfaceTiled(src: PSDL_Surface; srcrect: PSDL_Rect; dst: PSDL_S * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \threadsafety The same destination surface should not be used from two - * threads at once. It is safe to use the same source surface - * from multiple threads. + * \threadsafety Only one thread should be using the `src` and `dst` surfaces + * at any given time. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface } @@ -1286,11 +1379,10 @@ function SDL_BlitSurfaceTiledWithScale(src: PSDL_Surface; srcrect: PSDL_Rect; sc * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \threadsafety The same destination surface should not be used from two - * threads at once. It is safe to use the same source surface - * from multiple threads. + * \threadsafety Only one thread should be using the `src` and `dst` surfaces + * at any given time. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_BlitSurface } @@ -1321,7 +1413,9 @@ function SDL_BlitSurface9Grid(src: PSDL_Surface; srcrect: PSDL_Rect; left_width: * \param b the blue component of the pixel in the range 0-255. * \returns a pixel value. * - * \since This function is available since SDL 3.1.3. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MapSurfaceRGBA } @@ -1353,7 +1447,9 @@ function SDL_MapSurfaceRGB(surface: PSDL_Surface; r: cuint8; g: cuint8; b: cuint * \param a the alpha component of the pixel in the range 0-255. * \returns a pixel value. * - * \since This function is available since SDL 3.1.3. + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MapSurfaceRGB } @@ -1383,7 +1479,9 @@ function SDL_MapSurfaceRGBA(surface: PSDL_Surface; r: cuint8; g: cuint8; b: cuin * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. } function SDL_ReadSurfacePixel(surface: PSDL_Surface; x: cint; y: cint; r: pcuint8; g: pcuint8; b: pcuint8; a: pcuint8): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadSurfacePixel' {$ENDIF} {$ENDIF}; @@ -1408,7 +1506,9 @@ function SDL_ReadSurfacePixel(surface: PSDL_Surface; x: cint; y: cint; r: pcuint * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. } function SDL_ReadSurfacePixelFloat(surface: PSDL_Surface; x: cint; y: cint; r: pcfloat; g: pcfloat; b: pcfloat; a: pcfloat): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ReadSurfacePixelFloat' {$ENDIF} {$ENDIF}; @@ -1432,7 +1532,9 @@ function SDL_ReadSurfacePixelFloat(surface: PSDL_Surface; x: cint; y: cint; r: p * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. } function SDL_WriteSurfacePixel(surface: PSDL_Surface; x: cint; y: cint; r: cuint8; g: cuint8; b: cuint8; a: cuint8): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteSurfacePixel' {$ENDIF} {$ENDIF}; @@ -1453,7 +1555,9 @@ function SDL_WriteSurfacePixel(surface: PSDL_Surface; x: cint; y: cint; r: cuint * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function is not thread safe. + * + * \since This function is available since SDL 3.2.0. } function SDL_WriteSurfacePixelFloat(surface: PSDL_Surface; x: cint; y: cint; r: cfloat; g: cfloat; b: cfloat; a: cfloat): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WriteSurfacePixelFloat' {$ENDIF} {$ENDIF}; From 5115493db1ee3591fb8fcb5b4e9e505722b3ba85 Mon Sep 17 00:00:00 2001 From: suve Date: Thu, 14 Aug 2025 18:40:52 +0200 Subject: [PATCH 3/7] Update SDL_video.inc to match SDL 3.2.20 --- units/SDL3.pas | 4 +- units/SDL_video.inc | 690 +++++++++++++++++++++++++++++++++----------- 2 files changed, 529 insertions(+), 165 deletions(-) diff --git a/units/SDL3.pas b/units/SDL3.pas index 4c1c4da..bb677ca 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -93,7 +93,7 @@ interface {$I SDL_iostream.inc} // 3.2.0 {$I SDL_asyncio.inc} // 3.2.0 {$I SDL_surface.inc} // 3.2.20 -{$I SDL_video.inc} // 3.1.6-prev +{$I SDL_video.inc} // 3.2.20 {$I SDL_timer.inc} // 3.1.6-prev {$I SDL_error.inc} // 3.1.6-prev {$I SDL_power.inc} // 3.1.6-prev @@ -320,7 +320,7 @@ function SDL_MUSTLOCK(Const S: PSDL_Surface): Boolean; { Macros from SDL_video.h } function SDL_WINDOWPOS_UNDEFINED_DISPLAY(X: Integer): Integer; begin - Result := (SDL_WINDOWPOS_CENTERED_MASK or X); + Result := (SDL_WINDOWPOS_UNDEFINED_MASK or X); end; function SDL_WINDOWPOS_ISUNDEFINED(X: Integer): Boolean; diff --git a/units/SDL_video.inc b/units/SDL_video.inc index 9d680d1..9008841 100644 --- a/units/SDL_video.inc +++ b/units/SDL_video.inc @@ -40,7 +40,7 @@ * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.1.3. + * \since This datatype is available since SDL 3.2.0. } type PPSDL_DisplayID = ^PSDL_DisplayID; @@ -52,7 +52,7 @@ type * * The value 0 is an invalid ID. * - * \since This datatype is available since SDL 3.1.3. + * \since This datatype is available since SDL 3.2.0. } PPSDL_WindowID = ^PSDL_WindowID; PSDL_WindowID = ^TSDL_WindowID; @@ -80,7 +80,7 @@ const {* * System theme. * - * \since This enum is available since SDL 3.1.3. + * \since This enum is available since SDL 3.2.0. } type PPSDL_SystemTheme = ^PSDL_SystemTheme; @@ -91,15 +91,23 @@ const SDL_SYSTEM_THEME_LIGHT = TSDL_SystemTheme(1); {*< Light colored system theme } SDL_SYSTEM_THEME_DARK = TSDL_SystemTheme(2); {*< Dark colored system theme } -{ Internal display mode data } type PPSDL_DisplayModeData = ^PSDL_DisplayModeData; + {** + * Internal display mode data. + * + * This lives as a field in SDL_DisplayMode, as opaque data. + * + * \since This struct is available since SDL 3.2.0. + * + * \sa SDL_DisplayMode + *} PSDL_DisplayModeData = type Pointer; {* * The structure that defines a display mode. * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetFullscreenDisplayModes * \sa SDL_GetDesktopDisplayMode @@ -125,7 +133,7 @@ type {* * Display orientation values; the way a display is rotated. * - * \since This enum is available since SDL 3.1.3. + * \since This enum is available since SDL 3.2.0. } PPSDL_DisplayOrientation = ^PSDL_DisplayOrientation; PSDL_DisplayOrientation = ^TSDL_DisplayOrientation; @@ -140,7 +148,7 @@ const {* * The struct used as an opaque handle to a window. * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_CreateWindow } @@ -156,7 +164,7 @@ type * changed on existing windows by the app, and some of it might be altered by * the user or system outside of the app's control. * - * \since This datatype is available since SDL 3.1.3. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags } @@ -193,29 +201,89 @@ const SDL_WINDOW_NOT_FOCUSABLE = TSDL_WindowFlags($0000000080000000); {*< window should not be focusable } {* - * Used to indicate that you don't care what the window position is. + * A magic value used with SDL_WINDOWPOS_UNDEFINED. + * + * Generally this macro isn't used directly, but rather through + * SDL_WINDOWPOS_UNDEFINED or SDL_WINDOWPOS_UNDEFINED_DISPLAY. * - * \since This macro is available since SDL 3.1.3. + * \since This macro is available since SDL 3.2.0. } const SDL_WINDOWPOS_UNDEFINED_MASK = $1FFF0000; + +{* + * Used to indicate that you don't care what the window position is. + * + * If you _really_ don't care, SDL_WINDOWPOS_UNDEFINED is the same, but always + * uses the primary display instead of specifying one. + * + * \param X the SDL_DisplayID of the display to use. + * + * \since This macro is available since SDL 3.2.0. + *} function SDL_WINDOWPOS_UNDEFINED_DISPLAY(X: Integer): Integer; + +{* + * Used to indicate that you don't care what the window position/display is. + * + * This always uses the primary display. + * + * \since This macro is available since SDL 3.2.0. + *} const SDL_WINDOWPOS_UNDEFINED = SDL_WINDOWPOS_UNDEFINED_MASK or 0; // SDL3 for Pascal: No function call SDL_WINDOWPOS_UNDEFINED_DISPLAY(0) for performance + +{* + * A macro to test if the window position is marked as "undefined." + * + * \param X the window position value. + * + * \since This macro is available since SDL 3.2.0. + *} function SDL_WINDOWPOS_ISUNDEFINED(X: Integer): Boolean; {* - * Used to indicate that the window position should be centered. + * A magic value used with SDL_WINDOWPOS_CENTERED. * - * \since This macro is available since SDL 3.1.3. - } + * Generally this macro isn't used directly, but rather through + * SDL_WINDOWPOS_CENTERED or SDL_WINDOWPOS_CENTERED_DISPLAY. + * + * \since This macro is available since SDL 3.2.0. + *} const SDL_WINDOWPOS_CENTERED_MASK = $2FFF0000; + +{* + * Used to indicate that the window position should be centered. + * + * SDL_WINDOWPOS_CENTERED is the same, but always uses the primary display + * instead of specifying one. + * + * \param X the SDL_DisplayID of the display to use. + * + * \since This macro is available since SDL 3.2.0. + *} function SDL_WINDOWPOS_CENTERED_DISPLAY(X: Integer): Integer; + +{* + * Used to indicate that the window position should be centered. + * + * This always uses the primary display. + * + * \since This macro is available since SDL 3.2.0. + *} const SDL_WINDOWPOS_CENTERED = SDL_WINDOWPOS_CENTERED_MASK or 0; // SDL3 for Pascal: No function call SDL_WINDOWPOS_CENTERED_DISPLAY(0) for performance + +{* + * A macro to test if the window position is marked as "centered." + * + * \param X the window position value. + * + * \since This macro is available since SDL 3.2.0. + *} function SDL_WINDOWPOS_ISCENTERED(X: Integer): Boolean; {* * Window flash operation. * - * \since This enum is available since SDL 3.1.3. + * \since This enum is available since SDL 3.2.0. } type @@ -227,41 +295,61 @@ type SDL_FLASH_BRIEFLY = TSDL_FlashOperation(1); {*< Flash the window briefly to get attention } SDL_FLASH_UNTIL_FOCUSED = TSDL_FlashOperation(2); {*< Flash the window until it gets focus } -{* - * An opaque handle to an OpenGL context. - * - * \since This datatype is available since SDL 3.1.3. - * - * \sa SDL_GL_CreateContext - } type PPSDL_GLContext = ^PSDL_GLContext; PSDL_GLContext = ^TSDL_GLContext; + {* + * An opaque handle to an OpenGL context. + * + * \since This datatype is available since SDL 3.2.0. + * + * \sa SDL_GL_CreateContext + *} TSDL_GLContext = type Pointer; -{* - * Opaque EGL types. - * - * \since This datatype is available since SDL 3.1.3. - } PPSDL_EGLDisplay = ^PSDL_EGLDisplay; PSDL_EGLDisplay = ^TSDL_EGLDisplay; + {* + * Opaque type for an EGL display. + * + * \since This datatype is available since SDL 3.2.0. + *} TSDL_EGLDisplay = type Pointer; PPSDL_EGLConfig = ^PSDL_EGLConfig; PSDL_EGLConfig = ^TSDL_EGLConfig; + {* + * Opaque type for an EGL config. + * + * \since This datatype is available since SDL 3.2.0. + *} TSDL_EGLConfig = type Pointer; PPSDL_EGLSurface = ^PSDL_EGLSurface; PSDL_EGLSurface = ^TSDL_EGLSurface; + {* + * Opaque type for an EGL surface. + * + * \since This datatype is available since SDL 3.2.0. + *} TSDL_EGLSurface = type Pointer; PPSDL_EGLAttrib = ^PSDL_EGLAttrib; PSDL_EGLAttrib = ^TSDL_EGLAttrib; + {* + * An EGL attribute, used when creating an EGL context. + * + * \since This datatype is available since SDL 3.2.0. + *} TSDL_EGLAttrib = type cintptr_t; PPSDL_EGLint = ^PSDL_EGLint; PSDL_EGLint = ^TSDL_EGLint; + {* + * An EGL integer attribute, used when creating an EGL surface. + * + * \since This datatype is available since SDL 3.2.0. + *} TSDL_EGLint = type cint; {* @@ -283,7 +371,7 @@ type * \param userdata an app-controlled Pointer that is passed to the callback. * \returns a newly-allocated array of attributes, terminated with `EGL_NONE`. * - * \since This datatype is available since SDL 3.1.3. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_EGL_SetAttributeCallbacks } @@ -317,7 +405,7 @@ type * \param config the EGL config to be used. * \returns a newly-allocated array of attributes, terminated with `EGL_NONE`. * - * \since This datatype is available since SDL 3.1.3. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_EGL_SetAttributeCallbacks } @@ -340,16 +428,16 @@ type * fail if the GL can't provide your requested attributes at a minimum, but * you should check to see exactly what you got. * - * \since This enum is available since SDL 3.1.3. + * \since This enum is available since SDL 3.2.0. } PPSDL_GLAttr = ^PSDL_GLAttr; PSDL_GLAttr = ^TSDL_GLAttr; TSDL_GLAttr = Integer; const - SDL_GL_RED_SIZE = TSDL_GLAttr(0); {*< the minimum number of bits for the red channel of the color buffer; defaults to 3. } - SDL_GL_GREEN_SIZE = TSDL_GLAttr(1); {*< the minimum number of bits for the green channel of the color buffer; defaults to 3. } - SDL_GL_BLUE_SIZE = TSDL_GLAttr(2); {*< the minimum number of bits for the blue channel of the color buffer; defaults to 2. } - SDL_GL_ALPHA_SIZE = TSDL_GLAttr(3); {*< the minimum number of bits for the alpha channel of the color buffer; defaults to 0. } + SDL_GL_RED_SIZE = TSDL_GLAttr(0); {*< the minimum number of bits for the red channel of the color buffer; defaults to 8. } + SDL_GL_GREEN_SIZE = TSDL_GLAttr(1); {*< the minimum number of bits for the green channel of the color buffer; defaults to 8. } + SDL_GL_BLUE_SIZE = TSDL_GLAttr(2); {*< the minimum number of bits for the blue channel of the color buffer; defaults to 8. } + SDL_GL_ALPHA_SIZE = TSDL_GLAttr(3); {*< the minimum number of bits for the alpha channel of the color buffer; defaults to 8. } SDL_GL_BUFFER_SIZE = TSDL_GLAttr(4); {*< the minimum number of bits for frame buffer size; defaults to 0. } SDL_GL_DOUBLEBUFFER = TSDL_GLAttr(5); {*< whether the output is single or double buffered; defaults to double buffering on. } SDL_GL_DEPTH_SIZE = TSDL_GLAttr(6); {*< the minimum number of bits in the depth buffer; defaults to 16. } @@ -378,7 +466,7 @@ const {* * Possible values to be set for the SDL_GL_CONTEXT_PROFILE_MASK attribute. * - * \since This datatype is available since SDL 3.1.3. + * \since This datatype is available since SDL 3.2.0. } type PPSDL_GLProfile = ^PSDL_GLProfile; @@ -393,7 +481,7 @@ const {* * Possible flags to be set for the SDL_GL_CONTEXT_FLAGS attribute. * - * \since This datatype is available since SDL 3.1.3. + * \since This datatype is available since SDL 3.2.0. } type PPSDL_GLContextFlag = ^PSDL_GLContextFlag; @@ -409,7 +497,7 @@ const * Possible values to be set for the SDL_GL_CONTEXT_RELEASE_BEHAVIOR * attribute. * - * \since This datatype is available since SDL 3.1.3. + * \since This datatype is available since SDL 3.2.0. } type PPSDL_GLContextReleaseFlag = ^PSDL_GLContextReleaseFlag; @@ -423,7 +511,7 @@ const {* * Possible values to be set SDL_GL_CONTEXT_RESET_NOTIFICATION attribute. * - * \since This datatype is available since SDL 3.1.3. + * \since This datatype is available since SDL 3.2.0. } type PPSDL_GLContextResetNotification = ^PSDL_GLContextResetNotification; @@ -441,7 +529,9 @@ const * * \returns the number of built in video drivers. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetVideoDriver } @@ -461,7 +551,9 @@ function SDL_GetNumVideoDrivers: cint; cdecl; * \param index the index of a video driver. * \returns the name of the video driver with the given **index**. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumVideoDrivers } @@ -478,7 +570,9 @@ function SDL_GetVideoDriver(index: cint): PAnsiChar; cdecl; * \returns the name of the current video driver or nil if no driver has been * initialized. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetNumVideoDrivers * \sa SDL_GetVideoDriver @@ -491,7 +585,9 @@ function SDL_GetCurrentVideoDriver: PAnsiChar; cdecl; * * \returns the current system theme, light, dark, or unknown. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_GetSystemTheme: TSDL_SystemTheme; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetSystemTheme' {$ENDIF} {$ENDIF}; @@ -505,7 +601,9 @@ function SDL_GetSystemTheme: TSDL_SystemTheme; cdecl; * 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.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_GetDisplays(count: pcint): PSDL_DisplayID; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetDisplays' {$ENDIF} {$ENDIF}; @@ -516,7 +614,9 @@ function SDL_GetDisplays(count: pcint): PSDL_DisplayID; cdecl; * \returns the instance ID of the primary display on success or 0 on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays } @@ -545,7 +645,9 @@ function SDL_GetPrimaryDisplay: TSDL_DisplayID; cdecl; * \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.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_GetDisplayProperties(displayID: TSDL_DisplayID): TSDL_PropertiesID; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetDisplayProperties' {$ENDIF} {$ENDIF}; @@ -561,7 +663,9 @@ const * \returns the name of a display or nil on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays } @@ -571,14 +675,17 @@ function SDL_GetDisplayName(displayID: TSDL_DisplayID): PAnsiChar; cdecl; {* * Get the desktop area represented by a display. * - * The primary display is always located at (0,0). + * The primary display is often located at (0,0), but may be placed at a + * different location depending on monitor layout. * * \param displayID the instance ID of the display to query. * \param rect the SDL_Rect structure filled in with the display bounds. * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayUsableBounds * \sa SDL_GetDisplays @@ -603,7 +710,9 @@ function SDL_GetDisplayBounds(displayID: TSDL_DisplayID; rect: PSDL_Rect): Boole * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -618,7 +727,9 @@ function SDL_GetDisplayUsableBounds(displayID: TSDL_DisplayID; rect: PSDL_Rect): * \returns the SDL_DisplayOrientation enum value of the display, or * `SDL_ORIENTATION_UNKNOWN` if it isn't available. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays } @@ -632,7 +743,9 @@ function SDL_GetNaturalDisplayOrientation(displayID: TSDL_DisplayID): TSDL_Displ * \returns the SDL_DisplayOrientation enum value of the display, or * `SDL_ORIENTATION_UNKNOWN` if it isn't available. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays } @@ -647,12 +760,21 @@ function SDL_GetCurrentDisplayOrientation(displayID: TSDL_DisplayID): TSDL_Displ * display scale, which means that the user expects UI elements to be twice as * big on this display, to aid in readability. * + * After window creation, SDL_GetWindowDisplayScale() should be used to query + * the content scale factor for individual windows instead of querying the + * display for a window and calling this function, as the per-window content + * scale factor may differ from the base value of the display it is on, + * particularly on high-DPI and/or multi-monitor desktop configurations. + * * \param displayID the instance ID of the display to query. * \returns the content scale of the display, or 0.0f on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. * + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowDisplayScale * \sa SDL_GetDisplays } function SDL_GetDisplayContentScale(displayID: TSDL_DisplayID): cfloat; cdecl; @@ -678,7 +800,9 @@ function SDL_GetDisplayContentScale(displayID: TSDL_DisplayID): cfloat; cdecl; * single allocation that should be freed with SDL_free() when it is * no longer needed. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays } @@ -702,17 +826,19 @@ function SDL_GetFullscreenDisplayModes(displayID: TSDL_DisplayID; count: pcint): * for the desktop refresh rate. * \param include_high_density_modes boolean to include high density modes in * the search. - * \param mode a Pointer filled in with the closest display mode equal to or - * larger than the desired mode. + * \param closest a Pointer filled in with the closest display mode equal to + * or larger than the desired mode. * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplays * \sa SDL_GetFullscreenDisplayModes } -function SDL_GetClosestFullscreenDisplayMode(displayID: TSDL_DisplayID; w: cint; h: cint; refresh_rate: cfloat; include_high_density_modes: Boolean; mode: PSDL_DisplayMode): Boolean; cdecl; +function SDL_GetClosestFullscreenDisplayMode(displayID: TSDL_DisplayID; w: cint; h: cint; refresh_rate: cfloat; include_high_density_modes: Boolean; closest: PSDL_DisplayMode): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetClosestFullscreenDisplayMode' {$ENDIF} {$ENDIF}; {* @@ -727,7 +853,9 @@ function SDL_GetClosestFullscreenDisplayMode(displayID: TSDL_DisplayID; w: cint; * \returns a Pointer to the desktop display mode or nil on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetCurrentDisplayMode * \sa SDL_GetDisplays @@ -747,7 +875,9 @@ function SDL_GetDesktopDisplayMode(displayID: TSDL_DisplayID): PSDL_DisplayMode; * \returns a Pointer to the desktop display mode or nil on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDesktopDisplayMode * \sa SDL_GetDisplays @@ -762,7 +892,9 @@ function SDL_GetCurrentDisplayMode(displayID: TSDL_DisplayID): PSDL_DisplayMode; * \returns the instance ID of the display containing the point or 0 on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -778,7 +910,9 @@ function SDL_GetDisplayForPoint(point: PSDL_Point): TSDL_DisplayID; cdecl; * closest to the center of the rect on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -794,7 +928,9 @@ function SDL_GetDisplayForRect(rect: PSDL_Rect): TSDL_DisplayID; cdecl; * on success or 0 on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetDisplayBounds * \sa SDL_GetDisplays @@ -813,7 +949,9 @@ function SDL_GetDisplayForWindow(window: PSDL_Window): TSDL_DisplayID; cdecl; * \returns the pixel density or 0.0f on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowDisplayScale } @@ -838,7 +976,9 @@ function SDL_GetWindowPixelDensity(window: PSDL_Window): cfloat; cdecl; * \returns the display scale, or 0.0f on failure; call SDL_GetError() for * more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_GetWindowDisplayScale(window: PSDL_Window): cfloat; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetWindowDisplayScale' {$ENDIF} {$ENDIF}; @@ -868,7 +1008,9 @@ function SDL_GetWindowDisplayScale(window: PSDL_Window): cfloat; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFullscreenMode * \sa SDL_SetWindowFullscreen @@ -884,7 +1026,9 @@ function SDL_SetWindowFullscreenMode(window: PSDL_Window; mode: PSDL_DisplayMode * \returns a Pointer to the exclusive fullscreen mode to use or nil for * borderless fullscreen desktop mode. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowFullscreenMode * \sa SDL_SetWindowFullscreen @@ -901,7 +1045,9 @@ function SDL_GetWindowFullscreenMode(window: PSDL_Window): PSDL_DisplayMode; cde * 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.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_GetWindowICCProfile(window: PSDL_Window; size: pcsize_t): Pointer; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetWindowICCProfile' {$ENDIF} {$ENDIF}; @@ -914,7 +1060,9 @@ function SDL_GetWindowICCProfile(window: PSDL_Window; size: pcsize_t): Pointer; * SDL_PIXELFORMAT_UNKNOWN on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_GetWindowPixelFormat(window: PSDL_Window): TSDL_PixelFormat; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetWindowPixelFormat' {$ENDIF} {$ENDIF}; @@ -929,7 +1077,9 @@ function SDL_GetWindowPixelFormat(window: PSDL_Window): TSDL_PixelFormat; cdecl; * allocation that should be freed with SDL_free() when it is no * longer needed. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_GetWindows(count: pcint): PPSDL_Window; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetWindows' {$ENDIF} {$ENDIF}; @@ -937,6 +1087,10 @@ function SDL_GetWindows(count: pcint): PPSDL_Window; cdecl; {* * Create a window with the specified dimensions and flags. * + * The window size is a request and may be different than expected based on + * the desktop layout and window manager policies. Your application should be + * prepared to handle a window of any size. + * * `flags` may be any of the following OR'd together: * * - SDL_WINDOW_FULLSCREEN: fullscreen window at desktop resolution @@ -1009,7 +1163,9 @@ function SDL_GetWindows(count: pcint): PPSDL_Window; cdecl; * \returns the window that was created or nil on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindowAndRenderer * \sa SDL_CreatePopupWindow @@ -1022,6 +1178,10 @@ function SDL_CreateWindow(title: PAnsiChar; w: cint; h: cint; flags: TSDL_Window {* * Create a child popup window of the specified parent window. * + * The window size is a request and may be different than expected based on + * the desktop layout and window manager policies. Your application should be + * prepared to handle a window of any size. + * * The flags parameter **must** contain at least one of the following: * * - `SDL_WINDOW_TOOLTIP`: The popup window is a tooltip and will not pass any @@ -1054,6 +1214,15 @@ function SDL_CreateWindow(title: PAnsiChar; w: cint; h: cint; flags: TSDL_Window * Popup windows implicitly do not have a border/decorations and do not appear * on the taskbar/dock or in lists of windows such as alt-tab menus. * + * By default, popup window positions will automatically be constrained to keep + * the entire window within display bounds. This can be overridden with the + * `SDL_PROP_WINDOW_CREATE_CONSTRAIN_POPUP_BOOLEAN` property. + * + * By default, popup menus will automatically grab keyboard focus from the parent + * when shown. This behavior can be overridden by setting the `SDL_WINDOW_NOT_FOCUSABLE` + * flag, setting the `SDL_PROP_WINDOW_CREATE_FOCUSABLE_BOOLEAN` property to false, or + * toggling it after creation via the `SDL_SetWindowFocusable()` function. + * * If a parent window is hidden or destroyed, any child popup windows will be * recursively hidden or destroyed as well. Child popup windows not explicitly * hidden will be restored when the parent is shown. @@ -1070,7 +1239,9 @@ function SDL_CreateWindow(title: PAnsiChar; w: cint; h: cint; flags: TSDL_Window * \returns the window that was created or nil on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_CreateWindowWithProperties @@ -1083,12 +1254,19 @@ function SDL_CreatePopupWindow(parent: PSDL_Window; offset_x: cint; offset_y: ci {* * Create a window with the specified properties. * + * The window size is a request and may be different than expected based on + * the desktop layout and window manager policies. Your application should be + * prepared to handle a window of any size. + * * These are the supported properties: * * - `SDL_PROP_WINDOW_CREATE_ALWAYS_ON_TOP_BOOLEAN`: true if the window should * be always on top * - `SDL_PROP_WINDOW_CREATE_BORDERLESS_BOOLEAN`: true if the window has no * window decoration + * - `SDL_PROP_WINDOW_CREATE_CONSTRAIN_POPUP_BOOLEAN`: true if the "tooltip" and + * "menu" window types should be automatically constrained to be entirely within + * display bounds (default), false if no constraints on the position are desired. * - `SDL_PROP_WINDOW_CREATE_EXTERNAL_GRAPHICS_CONTEXT_BOOLEAN`: true if the * window will be used with an externally managed graphics context. @@ -1131,10 +1309,12 @@ function SDL_CreatePopupWindow(parent: PSDL_Window; offset_x: cint; offset_y: ci * - `SDL_PROP_WINDOW_CREATE_WIDTH_NUMBER`: the width of the window * - `SDL_PROP_WINDOW_CREATE_X_NUMBER`: the x position of the window, or * `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is - * relative to the parent for windows with the "parent" property set. + * relative to the parent for windows with the "tooltip" or "menu" property + * set. * - `SDL_PROP_WINDOW_CREATE_Y_NUMBER`: the y position of the window, or * `SDL_WINDOWPOS_CENTERED`, defaults to `SDL_WINDOWPOS_UNDEFINED`. This is - * relative to the parent for windows with the "parent" property set. + * relative to the parent for windows with the "tooltip" or "menu" property + * set. * * These are additional supported properties on macOS: * @@ -1190,7 +1370,9 @@ function SDL_CreatePopupWindow(parent: PSDL_Window; offset_x: cint; offset_y: ci * \returns the window that was created or nil on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateProperties * \sa SDL_CreateWindow @@ -1202,6 +1384,7 @@ function SDL_CreateWindowWithProperties(props: TSDL_PropertiesID): PSDL_Window; const SDL_PROP_WINDOW_CREATE_ALWAYS_ON_TOP_BOOLEAN = 'SDL.window.create.always_on_top'; SDL_PROP_WINDOW_CREATE_BORDERLESS_BOOLEAN = 'SDL.window.create.borderless'; + SDL_PROP_WINDOW_CREATE_CONSTRAIN_POPUP_BOOLEAN = 'SDL.window.create.constrain_popup'; SDL_PROP_WINDOW_CREATE_FOCUSABLE_BOOLEAN = 'SDL.window.create.focusable'; SDL_PROP_WINDOW_CREATE_EXTERNAL_GRAPHICS_CONTEXT_BOOLEAN = 'SDL.window.create.external_graphics_context'; SDL_PROP_WINDOW_CREATE_FLAGS_NUMBER = 'SDL.window.create.flags'; @@ -1245,7 +1428,9 @@ const * \returns the ID of the window on success or 0 on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFromID } @@ -1262,7 +1447,9 @@ function SDL_GetWindowID(window: PSDL_Window): TSDL_WindowID; cdecl; * \returns the window associated with `id` or nil if it doesn't exist; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowID } @@ -1276,7 +1463,9 @@ function SDL_GetWindowFromID(id: TSDL_WindowID): PSDL_Window; cdecl; * \returns the parent of the window on success or nil if the window has no * parent. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePopupWindow } @@ -1371,6 +1560,8 @@ function SDL_GetWindowParent(window: PSDL_Window): PSDL_Window; cdecl; * the window * - `SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER`: the wl_surface associated with * the window + * - `SDL_PROP_WINDOW_WAYLAND_VIEWPORT_POINTER`: the wp_viewport associated + * with the window * - `SDL_PROP_WINDOW_WAYLAND_EGL_WINDOW_POINTER`: the wl_egl_window * associated with the window * - `SDL_PROP_WINDOW_WAYLAND_XDG_SURFACE_POINTER`: the xdg_surface associated @@ -1397,7 +1588,9 @@ function SDL_GetWindowParent(window: PSDL_Window): PSDL_Window; cdecl; * \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.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_GetWindowProperties(window: PSDL_Window): TSDL_PropertiesID; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetWindowProperties' {$ENDIF} {$ENDIF}; @@ -1428,6 +1621,7 @@ const SDL_PROP_WINDOW_WIN32_INSTANCE_POINTER = 'SDL.window.win32.instance'; SDL_PROP_WINDOW_WAYLAND_DISPLAY_POINTER = 'SDL.window.wayland.display'; SDL_PROP_WINDOW_WAYLAND_SURFACE_POINTER = 'SDL.window.wayland.surface'; + SDL_PROP_WINDOW_WAYLAND_VIEWPORT_POINTER = 'SDL.window.wayland.viewport'; SDL_PROP_WINDOW_WAYLAND_EGL_WINDOW_POINTER = 'SDL.window.wayland.egl_window'; SDL_PROP_WINDOW_WAYLAND_XDG_SURFACE_POINTER = 'SDL.window.wayland.xdg_surface'; SDL_PROP_WINDOW_WAYLAND_XDG_TOPLEVEL_POINTER = 'SDL.window.wayland.xdg_toplevel'; @@ -1444,7 +1638,9 @@ const * \param window the window to query. * \returns a mask of the SDL_WindowFlags associated with `window`. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_HideWindow @@ -1467,7 +1663,9 @@ function SDL_GetWindowFlags(window: PSDL_Window): TSDL_WindowFlags; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowTitle } @@ -1481,7 +1679,9 @@ function SDL_SetWindowTitle(window: PSDL_Window; title: PAnsiChar): Boolean; cde * \returns the title of the window in UTF-8 format or "" if there is no * title. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowTitle } @@ -1506,7 +1706,9 @@ function SDL_GetWindowTitle(window: PSDL_Window): PAnsiChar; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_SetWindowIcon(window: PSDL_Window; icon: PSDL_Surface): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetWindowIcon' {$ENDIF} {$ENDIF}; @@ -1514,13 +1716,12 @@ function SDL_SetWindowIcon(window: PSDL_Window; icon: PSDL_Surface): Boolean; cd {* * Request that the window's position be set. * - * If, at the time of this request, the window is in a fixed-size state such - * as maximized, this request may be deferred until the window returns to a - * resizable state. + * If the window is in an exclusive fullscreen or maximized state, this + * request has no effect. * * This can be used to reposition fullscreen-desktop windows onto a different - * display, however, exclusive fullscreen windows are locked to a specific - * display and can only be repositioned programmatically via + * display, however, as exclusive fullscreen windows are locked to a specific + * display, they can only be repositioned programmatically via * SDL_SetWindowFullscreenMode(). * * On some windowing systems this request is asynchronous and the new @@ -1544,7 +1745,9 @@ function SDL_SetWindowIcon(window: PSDL_Window; icon: PSDL_Surface): Boolean; cd * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowPosition * \sa SDL_SyncWindow @@ -1569,7 +1772,9 @@ function SDL_SetWindowPosition(window: PSDL_Window; x: cint; y: cint): Boolean; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowPosition } @@ -1579,12 +1784,11 @@ function SDL_GetWindowPosition(window: PSDL_Window; x: pcint; y: pcint): Boolean {* * Request that the size of a window's client area be set. * - * If, at the time of this request, the window in a fixed-size state, such as - * maximized or fullscreen, the request will be deferred until the window - * exits this state and becomes resizable again. + * If the window is in a fullscreen or maximized state, this request has no + * effect. * - * To change the fullscreen mode of a window, use - * SDL_SetWindowFullscreenMode() + * To change the exclusive fullscreen mode of a window, use + * SDL_SetWindowFullscreenMode(). * * On some windowing systems, this request is asynchronous and the new window * size may not have have been applied immediately upon the return of this @@ -1604,7 +1808,9 @@ function SDL_GetWindowPosition(window: PSDL_Window; x: pcint; y: pcint): Boolean * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSize * \sa SDL_SetWindowFullscreenMode @@ -1626,7 +1832,9 @@ function SDL_SetWindowSize(window: PSDL_Window; w: cint; h: cint): Boolean; cdec * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetRenderOutputSize * \sa SDL_GetWindowSizeInPixels @@ -1651,7 +1859,9 @@ function SDL_GetWindowSize(window: PSDL_Window; w: pcint; h: pcint): Boolean; cd * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_GetWindowSafeArea(window: PSDL_Window; rect: PSDL_Rect): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetWindowSafeArea' {$ENDIF} {$ENDIF}; @@ -1688,7 +1898,9 @@ function SDL_GetWindowSafeArea(window: PSDL_Window; rect: PSDL_Rect): Boolean; c * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowAspectRatio * \sa SDL_SyncWindow @@ -1707,7 +1919,9 @@ function SDL_SetWindowAspectRatio(window: PSDL_Window; min_aspect: cfloat; max_a * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowAspectRatio } @@ -1743,7 +1957,9 @@ function SDL_GetWindowAspectRatio(window: PSDL_Window; min_aspect: pcfloat; max_ * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSize } @@ -1761,7 +1977,9 @@ function SDL_GetWindowBordersSize(window: PSDL_Window; top: pcint; left: pcint; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreateWindow * \sa SDL_GetWindowSize @@ -1778,7 +1996,9 @@ function SDL_GetWindowSizeInPixels(window: PSDL_Window; w: pcint; h: pcint): Boo * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMinimumSize * \sa SDL_SetWindowMaximumSize @@ -1797,7 +2017,9 @@ function SDL_SetWindowMinimumSize(window: PSDL_Window; min_w: cint; min_h: cint) * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMaximumSize * \sa SDL_SetWindowMinimumSize @@ -1814,7 +2036,9 @@ function SDL_GetWindowMinimumSize(window: PSDL_Window; w: pcint; h: pcint): Bool * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMaximumSize * \sa SDL_SetWindowMinimumSize @@ -1833,7 +2057,9 @@ function SDL_SetWindowMaximumSize(window: PSDL_Window; max_w: cint; max_h: cint) * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMinimumSize * \sa SDL_SetWindowMaximumSize @@ -1855,7 +2081,9 @@ function SDL_GetWindowMaximumSize(window: PSDL_Window; w: pcint; h: pcint): Bool * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags } @@ -1876,7 +2104,9 @@ function SDL_SetWindowBordered(window: PSDL_Window; bordered: Boolean): Boolean; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags } @@ -1894,7 +2124,9 @@ function SDL_SetWindowResizable(window: PSDL_Window; resizable: Boolean): Boolea * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFlags } @@ -1908,7 +2140,9 @@ function SDL_SetWindowAlwaysOnTop(window: PSDL_Window; on_top: Boolean): Boolean * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_HideWindow * \sa SDL_RaiseWindow @@ -1923,9 +2157,12 @@ function SDL_ShowWindow(window: PSDL_Window): Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_ShowWindow + * \sa SDL_WINDOW_HIDDEN } function SDL_HideWindow(window: PSDL_Window): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_HideWindow' {$ENDIF} {$ENDIF}; @@ -1944,7 +2181,9 @@ function SDL_HideWindow(window: PSDL_Window): Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_RaiseWindow(window: PSDL_Window): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_RaiseWindow' {$ENDIF} {$ENDIF}; @@ -1973,7 +2212,9 @@ function SDL_RaiseWindow(window: PSDL_Window): Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MinimizeWindow * \sa SDL_RestoreWindow @@ -1985,6 +2226,9 @@ function SDL_MaximizeWindow(window: PSDL_Window): Boolean; cdecl; {* * Request that the window be minimized to an iconic representation. * + * If the window is in a fullscreen state, this request has no direct effect. + * It may alter the state the window is returned to when leaving fullscreen. + * * On some windowing systems this request is asynchronous and the new window * state may not have been applied immediately upon the return of this * function. If an immediate change is required, call SDL_SyncWindow() to @@ -1998,7 +2242,9 @@ function SDL_MaximizeWindow(window: PSDL_Window): Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MaximizeWindow * \sa SDL_RestoreWindow @@ -2011,6 +2257,9 @@ function SDL_MinimizeWindow(window: PSDL_Window): Boolean; cdecl; * Request that the size and position of a minimized or maximized window be * restored. * + * If the window is in a fullscreen state, this request has no direct effect. + * It may alter the state the window is returned to when leaving fullscreen. + * * On some windowing systems this request is asynchronous and the new window * state may not have have been applied immediately upon the return of this * function. If an immediate change is required, call SDL_SyncWindow() to @@ -2024,7 +2273,9 @@ function SDL_MinimizeWindow(window: PSDL_Window): Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_MaximizeWindow * \sa SDL_MinimizeWindow @@ -2054,11 +2305,14 @@ function SDL_RestoreWindow(window: PSDL_Window): Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowFullscreenMode * \sa SDL_SetWindowFullscreenMode * \sa SDL_SyncWindow + * \sa SDL_WINDOW_FULLSCREEN } function SDL_SetWindowFullscreen(window: PSDL_Window; fullscreen: Boolean): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetWindowFullscreen' {$ENDIF} {$ENDIF}; @@ -2080,7 +2334,9 @@ function SDL_SetWindowFullscreen(window: PSDL_Window; fullscreen: Boolean): Bool * \returns true on success or false if the operation timed out before the * window was in the requested state. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowSize * \sa SDL_SetWindowPosition @@ -2100,7 +2356,9 @@ function SDL_SyncWindow(window: PSDL_Window): Boolean; cdecl; * \returns true if there is a surface associated with the window, or false * otherwise. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface } @@ -2125,7 +2383,9 @@ function SDL_WindowHasSurface(window: PSDL_Window): Boolean; cdecl; * \returns the surface associated with the window, or nil on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DestroyWindowSurface * \sa SDL_WindowHasSurface @@ -2153,7 +2413,9 @@ function SDL_GetWindowSurface(window: PSDL_Window): PSDL_Surface; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurfaceVSync } @@ -2173,7 +2435,9 @@ function SDL_SetWindowSurfaceVSync(window: PSDL_Window; vsync: cint): Boolean; c * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowSurfaceVSync } @@ -2192,7 +2456,9 @@ function SDL_GetWindowSurfaceVSync(window: PSDL_Window; vsync: pcint): Boolean; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_UpdateWindowSurfaceRects @@ -2220,7 +2486,9 @@ function SDL_UpdateWindowSurface(window: PSDL_Window): Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_UpdateWindowSurface @@ -2235,7 +2503,9 @@ function SDL_UpdateWindowSurfaceRects(window: PSDL_Window; rects: PSDL_Rect; num * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowSurface * \sa SDL_WindowHasSurface @@ -2267,7 +2537,9 @@ function SDL_DestroyWindowSurface(window: PSDL_Window): Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowKeyboardGrab * \sa SDL_SetWindowMouseGrab @@ -2285,9 +2557,14 @@ function SDL_SetWindowKeyboardGrab(window: PSDL_Window; grabbed: Boolean): Boole * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. * * \sa SDL_GetWindowMouseGrab + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_GetWindowMouseGrab + * \sa SDL_GetWindowMouseRect + * \sa SDL_SetWindowMouseRect * \sa SDL_SetWindowKeyboardGrab } function SDL_SetWindowMouseGrab(window: PSDL_Window; grabbed: Boolean): Boolean; cdecl; @@ -2299,7 +2576,9 @@ function SDL_SetWindowMouseGrab(window: PSDL_Window; grabbed: Boolean): Boolean; * \param window the window to query. * \returns true if keyboard is grabbed, and false otherwise. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowKeyboardGrab } @@ -2312,8 +2591,13 @@ function SDL_GetWindowKeyboardGrab(window: PSDL_Window): Boolean; cdecl; * \param window the window to query. * \returns true if mouse is grabbed, and false otherwise. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * + * \sa SDL_GetWindowMouseRect + * \sa SDL_SetWindowMouseRect + * \sa SDL_SetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab } function SDL_GetWindowMouseGrab(window: PSDL_Window): Boolean; cdecl; @@ -2324,7 +2608,9 @@ function SDL_GetWindowMouseGrab(window: PSDL_Window): Boolean; cdecl; * * \returns the window if input is grabbed or nil otherwise. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowMouseGrab * \sa SDL_SetWindowKeyboardGrab @@ -2344,9 +2630,12 @@ function SDL_GetGrabbedWindow: PSDL_Window; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowMouseRect + * \sa SDL_GetWindowMouseGrab * \sa SDL_SetWindowMouseGrab } function SDL_SetWindowMouseRect(window: PSDL_Window; rect: PSDL_Rect): Boolean; cdecl; @@ -2359,9 +2648,13 @@ function SDL_SetWindowMouseRect(window: PSDL_Window; rect: PSDL_Rect): Boolean; * \returns a Pointer to the mouse confinement rectangle of a window, or nil * if there isn't one. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowMouseRect + * \sa SDL_GetWindowMouseGrab + * \sa SDL_SetWindowMouseGrab } function SDL_GetWindowMouseRect(window: PSDL_Window): PSDL_Rect; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetWindowMouseRect' {$ENDIF} {$ENDIF}; @@ -2379,7 +2672,9 @@ function SDL_GetWindowMouseRect(window: PSDL_Window): PSDL_Rect; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetWindowOpacity } @@ -2396,7 +2691,9 @@ function SDL_SetWindowOpacity(window: PSDL_Window; opacity: cfloat): Boolean; cd * \returns the opacity, (0.0f - transparent, 1.0f - opaque), or -1.0f on * failure; call SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowOpacity } @@ -2429,7 +2726,9 @@ function SDL_GetWindowOpacity(window: PSDL_Window): cfloat; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowModal } @@ -2447,9 +2746,12 @@ function SDL_SetWindowParent(window: PSDL_Window; parent: PSDL_Window): Boolean; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetWindowParent + * \sa SDL_WINDOW_MODAL } function SDL_SetWindowModal(window: PSDL_Window; modal: Boolean): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetWindowModal' {$ENDIF} {$ENDIF}; @@ -2462,7 +2764,9 @@ function SDL_SetWindowModal(window: PSDL_Window; modal: Boolean): Boolean; cdecl * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_SetWindowFocusable(window: PSDL_Window; focusable: Boolean): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetWindowFocusable' {$ENDIF} {$ENDIF}; @@ -2486,7 +2790,9 @@ function SDL_SetWindowFocusable(window: PSDL_Window; focusable: Boolean): Boolea * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_ShowWindowSystemMenu(window: PSDL_Window; x: cint; y: cint): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ShowWindowSystemMenu' {$ENDIF} {$ENDIF}; @@ -2494,7 +2800,7 @@ function SDL_ShowWindowSystemMenu(window: PSDL_Window; x: cint; y: cint): Boolea {* * Possible return values from the SDL_HitTest callback. * - * \since This enum is available since SDL 3.1.3. + * \since This enum is available since SDL 3.2.0. * * \sa SDL_HitTest } @@ -2565,7 +2871,9 @@ type * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_SetWindowHitTest(window: PSDL_Window; callback: TSDL_HitTest; callback_data: Pointer): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetWindowHitTest' {$ENDIF} {$ENDIF}; @@ -2592,7 +2900,9 @@ function SDL_SetWindowHitTest(window: PSDL_Window; callback: TSDL_HitTest; callb * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_SetWindowShape(window: PSDL_Window; shape: PSDL_Surface): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetWindowShape' {$ENDIF} {$ENDIF}; @@ -2605,7 +2915,9 @@ function SDL_SetWindowShape(window: PSDL_Window; shape: PSDL_Surface): Boolean; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_FlashWindow(window: PSDL_Window; operation: TSDL_FlashOperation): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_FlashWindow' {$ENDIF} {$ENDIF}; @@ -2616,9 +2928,15 @@ function SDL_FlashWindow(window: PSDL_Window; operation: TSDL_FlashOperation): B * Any child windows owned by the window will be recursively destroyed as * well. * + * Note that on some platforms, the visible window may not actually be removed + * from the screen until the SDL event loop is pumped again, even though the + * SDL_Window is no longer valid after this call. + * * \param window the window to destroy. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_CreatePopupWindow * \sa SDL_CreateWindow @@ -2636,7 +2954,9 @@ procedure SDL_DestroyWindow(window: PSDL_Window); cdecl; * * \returns true if the screensaver is enabled, false if it is disabled. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DisableScreenSaver * \sa SDL_EnableScreenSaver @@ -2650,7 +2970,9 @@ function SDL_ScreenSaverEnabled: Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_DisableScreenSaver * \sa SDL_ScreenSaverEnabled @@ -2670,7 +2992,9 @@ function SDL_EnableScreenSaver: Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_EnableScreenSaver * \sa SDL_ScreenSaverEnabled @@ -2697,7 +3021,9 @@ function SDL_DisableScreenSaver: Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetProcAddress * \sa SDL_GL_UnloadLibrary @@ -2750,7 +3076,9 @@ function SDL_GL_LoadLibrary(path: PAnsiChar): Boolean; cdecl; * \returns a Pointer to the named OpenGL function. The returned Pointer * should be cast to the appropriate function signature. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_ExtensionSupported * \sa SDL_GL_LoadLibrary @@ -2770,7 +3098,9 @@ function SDL_GL_GetProcAddress(proc: PAnsiChar): TSDL_FunctionPointer; cdecl; * \returns a Pointer to the named EGL function. The returned Pointer should * be cast to the appropriate function signature. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_EGL_GetCurrentDisplay } @@ -2780,7 +3110,9 @@ function SDL_EGL_GetProcAddress(proc: PAnsiChar): TSDL_FunctionPointer; cdecl; {* * Unload the OpenGL library previously loaded by SDL_GL_LoadLibrary(). * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_LoadLibrary } @@ -2804,7 +3136,9 @@ procedure SDL_GL_UnloadLibrary; cdecl; * \param extension the name of the extension to check. * \returns true if the extension is supported, false otherwise. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_GL_ExtensionSupported(extension: PAnsiChar): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GL_ExtensionSupported' {$ENDIF} {$ENDIF}; @@ -2812,7 +3146,9 @@ function SDL_GL_ExtensionSupported(extension: PAnsiChar): Boolean; cdecl; {* * Reset all previously set OpenGL context attributes to their default values. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetAttribute * \sa SDL_GL_SetAttribute @@ -2834,7 +3170,9 @@ procedure SDL_GL_ResetAttributes; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetAttribute * \sa SDL_GL_ResetAttributes @@ -2851,7 +3189,9 @@ function SDL_GL_SetAttribute(attr: TSDL_GLAttr; value: cint): Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_ResetAttributes * \sa SDL_GL_SetAttribute @@ -2874,7 +3214,9 @@ function SDL_GL_GetAttribute(attr: TSDL_GLAttr; value: pcint): Boolean; cdecl; * \returns the OpenGL context associated with `window` or nil on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_DestroyContext * \sa SDL_GL_MakeCurrent @@ -2892,7 +3234,9 @@ function SDL_GL_CreateContext(window: PSDL_Window): TSDL_GLContext; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_CreateContext } @@ -2905,7 +3249,9 @@ function SDL_GL_MakeCurrent(window: PSDL_Window; context: TSDL_GLContext): Boole * \returns the currently active OpenGL window on success or nil on failure; * call SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_GL_GetCurrentWindow: PSDL_Window; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GL_GetCurrentWindow' {$ENDIF} {$ENDIF}; @@ -2916,7 +3262,9 @@ function SDL_GL_GetCurrentWindow: PSDL_Window; cdecl; * \returns the currently active OpenGL context or nil on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_MakeCurrent } @@ -2929,7 +3277,9 @@ function SDL_GL_GetCurrentContext: TSDL_GLContext; cdecl; * \returns the currently active EGL display or nil on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_EGL_GetCurrentDisplay: TSDL_EGLDisplay; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_EGL_GetCurrentDisplay' {$ENDIF} {$ENDIF}; @@ -2940,7 +3290,9 @@ function SDL_EGL_GetCurrentDisplay: TSDL_EGLDisplay; cdecl; * \returns the currently active EGL config or nil on failure; call * SDL_GetError() for more information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_EGL_GetCurrentConfig: TSDL_EGLConfig; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_EGL_GetCurrentConfig' {$ENDIF} {$ENDIF}; @@ -2952,7 +3304,9 @@ function SDL_EGL_GetCurrentConfig: TSDL_EGLConfig; cdecl; * \returns the EGLSurface Pointer associated with the window, or nil on * failure. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_EGL_GetWindowSurface(window: PSDL_Window): TSDL_EGLSurface; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_EGL_GetWindowSurface' {$ENDIF} {$ENDIF}; @@ -2973,7 +3327,9 @@ function SDL_EGL_GetWindowSurface(window: PSDL_Window): TSDL_EGLSurface; cdecl; * eglCreateContext. May be nil. * \param userdata a Pointer that is passed to the callbacks. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } procedure SDL_EGL_SetAttributeCallbacks(platformAttribCallback: TSDL_EGLAttribArrayCallback; surfaceAttribCallback: TSDL_EGLIntArrayCallback; contextAttribCallback: TSDL_EGLIntArrayCallback; userdata: Pointer); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_EGL_SetAttributeCallbacks' {$ENDIF} {$ENDIF}; @@ -3001,7 +3357,9 @@ procedure SDL_EGL_SetAttributeCallbacks(platformAttribCallback: TSDL_EGLAttribAr * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_GetSwapInterval } @@ -3021,7 +3379,9 @@ function SDL_GL_SetSwapInterval(interval: cint): Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_SetSwapInterval } @@ -3042,7 +3402,9 @@ function SDL_GL_GetSwapInterval(interval: pcint): Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. } function SDL_GL_SwapWindow(window: PSDL_Window): Boolean; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GL_SwapWindow' {$ENDIF} {$ENDIF}; @@ -3054,7 +3416,9 @@ function SDL_GL_SwapWindow(window: PSDL_Window): Boolean; cdecl; * \returns true on success or false on failure; call SDL_GetError() for more * information. * - * \since This function is available since SDL 3.1.3. + * \threadsafety This function should only be called on the main thread. + * + * \since This function is available since SDL 3.2.0. * * \sa SDL_GL_CreateContext } From b2102d5825e9908b0ed75a89ae07348df827b377 Mon Sep 17 00:00:00 2001 From: suve Date: Thu, 14 Aug 2025 19:07:27 +0200 Subject: [PATCH 4/7] Update SDL_timer.inc to match SDL 3.2.20 --- units/SDL3.pas | 2 +- units/SDL_timer.inc | 168 ++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 156 insertions(+), 14 deletions(-) diff --git a/units/SDL3.pas b/units/SDL3.pas index bb677ca..84190c1 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -94,7 +94,7 @@ interface {$I SDL_asyncio.inc} // 3.2.0 {$I SDL_surface.inc} // 3.2.20 {$I SDL_video.inc} // 3.2.20 -{$I SDL_timer.inc} // 3.1.6-prev +{$I SDL_timer.inc} // 3.2.20 {$I SDL_error.inc} // 3.1.6-prev {$I SDL_power.inc} // 3.1.6-prev {$I SDL_audio.inc} // 3.1.6-prev diff --git a/units/SDL_timer.inc b/units/SDL_timer.inc index f1c9894..21df010 100644 --- a/units/SDL_timer.inc +++ b/units/SDL_timer.inc @@ -9,22 +9,155 @@ {* * # CategoryTimer * - * SDL time management routines. + * SDL provides time management functionality. It is useful for dealing with + * (usually) small durations of time. + * + * This is not to be confused with _calendar time_ management, which is + * provided by [CategoryTime](CategoryTime). + * + * This category covers measuring time elapsed (SDL_GetTicks(), + * SDL_GetPerformanceCounter()), putting a thread to sleep for a certain + * amount of time (SDL_Delay(), SDL_DelayNS(), SDL_DelayPrecise()), and firing + * a callback function after a certain amount of time has elasped + * (SDL_AddTimer(), etc). + * + * There are also useful macros to convert between time units, like + * SDL_SECONDS_TO_NS() and such. } { SDL time constants } const + {* + * Number of milliseconds in a second. + * + * This is always 1000. + * + * \since This const is available since SDL 3.2.0. + *} SDL_MS_PER_SECOND = 1000; + + {* + * Number of microseconds in a second. + * + * This is always 1000000. + * + * \since This const is available since SDL 3.2.0. + *} SDL_US_PER_SECOND = 1000000; + + {* + * Number of nanoseconds in a second. + * + * This is always 1000000000. + * + * \since This const is available since SDL 3.2.0. + *} SDL_NS_PER_SECOND = 1000000000; + + {* + * Number of nanoseconds in a millisecond. + * + * This is always 1000000. + * + * \since This macro is available since SDL 3.2.0. + *} SDL_NS_PER_MS = 1000000; + + {* + * Number of nanoseconds in a microsecond. + * + * This is always 1000. + * + * \since This macro is available since SDL 3.2.0. + *} SDL_NS_PER_US = 1000; + +{* + * Convert seconds to nanoseconds. + * + * This only converts whole numbers, not fractional seconds. + * + * \param S the number of seconds to convert. + * \returns S, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + *} function SDL_SECONDS_TO_NS(S: Integer): Integer; + +{* + * Convert nanoseconds to seconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in seconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + *} function SDL_NS_TO_SECONDS(NS: Integer): Integer; + +{* + * Convert milliseconds to nanoseconds. + * + * This only converts whole numbers, not fractional milliseconds. + * + * \param MS the number of milliseconds to convert. + * \returns MS, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + *} function SDL_MS_TO_NS(MS: Integer): Integer; + +{* + * Convert nanoseconds to milliseconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in milliseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + *} function SDL_NS_TO_MS(NS: Integer): Integer; + +{* + * Convert microseconds to nanoseconds. + * + * This only converts whole numbers, not fractional microseconds. + * + * \param US the number of microseconds to convert. + * \returns US, expressed in nanoseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + *} function SDL_US_TO_NS(US: Integer): Integer; + +{* + * Convert nanoseconds to microseconds. + * + * This performs a division, so the results can be dramatically different if + * `NS` is an integer or floating point value. + * + * \param NS the number of nanoseconds to convert. + * \returns NS, expressed in microseconds. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.2.0. + *} function SDL_NS_TO_US(NS: Integer): Integer; {* @@ -35,7 +168,7 @@ function SDL_NS_TO_US(NS: Integer): Integer; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. } function SDL_GetTicks: cuint64; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetTicks' {$ENDIF} {$ENDIF}; @@ -48,7 +181,7 @@ function SDL_GetTicks: cuint64; cdecl; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. } function SDL_GetTicksNS: cuint64; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetTicksNS' {$ENDIF} {$ENDIF}; @@ -66,7 +199,7 @@ function SDL_GetTicksNS: cuint64; cdecl; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPerformanceFrequency } @@ -80,7 +213,7 @@ function SDL_GetPerformanceCounter: cuint64; cdecl; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetPerformanceCounter } @@ -98,7 +231,10 @@ function SDL_GetPerformanceFrequency: cuint64; cdecl; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_DelayNS + * \sa SDL_DelayPrecise } procedure SDL_Delay(ms: cuint32); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_Delay' {$ENDIF} {$ENDIF}; @@ -114,7 +250,10 @@ procedure SDL_Delay(ms: cuint32); cdecl; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Delay + * \sa SDL_DelayPrecise } procedure SDL_DelayNS(ns: cuint64); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DelayNS' {$ENDIF} {$ENDIF}; @@ -131,6 +270,9 @@ procedure SDL_DelayNS(ns: cuint64); cdecl; * \threadsafety It is safe to call this function from any thread. * * \since This function is available since SDL 3.2.0. + * + * \sa SDL_Delay + * \sa SDL_DelayNS } procedure SDL_DelayPrecise(ns: cuint64); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DelayPrecise' {$ENDIF} {$ENDIF}; @@ -138,7 +280,7 @@ procedure SDL_DelayPrecise(ns: cuint64); cdecl; {* * Definition of the timer ID type. * - * \since This datatype is available since SDL 3.1.3. + * \since This datatype is available since SDL 3.2.0. } type PPSDL_TimerID = ^PSDL_TimerID; @@ -165,7 +307,7 @@ type * thread; the application is responsible for locking resources * the callback touches that need to be protected. * - * \since This datatype is available since SDL 3.1.3. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_AddTimer } @@ -201,7 +343,7 @@ type * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimerNS * \sa SDL_RemoveTimer @@ -229,7 +371,7 @@ function SDL_AddTimer(interval: cuint32; callback: TSDL_TimerCallback; userdata: * thread; the application is responsible for locking resources * the callback touches that need to be protected. * - * \since This datatype is available since SDL 3.1.3. + * \since This datatype is available since SDL 3.2.0. * * \sa SDL_AddTimerNS } @@ -265,7 +407,7 @@ type * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimer * \sa SDL_RemoveTimer @@ -282,7 +424,7 @@ function SDL_AddTimerNS(interval: cuint64; callback: TSDL_NSTimerCallback; userd * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddTimer } From 587368beefa9c88a127f9816223a8cd6283a7c8a Mon Sep 17 00:00:00 2001 From: suve Date: Thu, 14 Aug 2025 19:15:17 +0200 Subject: [PATCH 5/7] Update SDL_keycode.inc to match SDL 3.2.20 --- units/SDL3.pas | 2 +- units/SDL_keycode.inc | 21 +++++++++++++++++++-- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/units/SDL3.pas b/units/SDL3.pas index 84190c1..7698bad 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -100,7 +100,7 @@ interface {$I SDL_audio.inc} // 3.1.6-prev {$I SDL_sensor.inc} // 3.1.6-prev {$I SDL_scancode.inc} // 3.1.6-prev -{$I SDL_keycode.inc} // 3.1.6-prev +{$I SDL_keycode.inc} // 3.2.20 {$I SDL_mouse.inc} // 3.1.6-prev {$I SDL_keyboard.inc} // 3.1.6-prev {$I SDL_joystick.inc} // 3.1.6-prev diff --git a/units/SDL_keycode.inc b/units/SDL_keycode.inc index f590da3..302e77c 100644 --- a/units/SDL_keycode.inc +++ b/units/SDL_keycode.inc @@ -10,6 +10,11 @@ * # CategoryKeycode * * Defines constants which identify keyboard keys and modifiers. + * + * Please refer to the Best Keyboard Practices document for details on what + * this information means and how best to use it. + * + * https://wiki.libsdl.org/SDL3/BestKeyboardPractices } {* @@ -23,7 +28,10 @@ * A special exception is the number keys at the top of the keyboard which map * to SDLK_0...SDLK_9 on AZERTY layouts. * - * \since This datatype is available since SDL 3.1.3. + * Keys with the `SDLK_EXTENDED_MASK` bit set do not map to a scancode or + * unicode code point. + * + * \since This datatype is available since SDL 3.2.0. } type PPSDL_Keycode = ^PSDL_Keycode; @@ -31,6 +39,7 @@ type TSDL_Keycode = type cuint32; const + SDLK_EXTENDED_MASK = 1 shl 29; SDLK_SCANCODE_MASK = 1 shl 30; function SDL_SCANCODE_TO_KEYCODE(X: TSDL_Scancode): TSDL_Keycode; {SDL3-for-Pascal: C Macro} const @@ -283,11 +292,18 @@ const SDLK_SOFTRIGHT = TSDL_Keycode($40000120); {*< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_SOFTRIGHT) } SDLK_CALL = TSDL_Keycode($40000121); {*< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_CALL) } SDLK_ENDCALL = TSDL_Keycode($40000122); {*< SDL_SCANCODE_TO_KEYCODE(SDL_SCANCODE_ENDCALL) } + SDLK_LEFT_TAB = TSDL_Keycode($20000001); {*< Extended key Left Tab } + SDLK_LEVEL5_SHIFT = TSDL_Keycode($20000002); {*< Extended key Level 5 Shift } + SDLK_MULTI_KEY_COMPOSE = TSDL_Keycode($20000003); {*< Extended key Multi-key Compose } + SDLK_LMETA = TSDL_Keycode($20000004); {*< Extended key Left Meta } + SDLK_RMETA = TSDL_Keycode($20000005); {*< Extended key Right Meta } + SDLK_LHYPER = TSDL_Keycode($20000006); {*< Extended key Left Hyper } + SDLK_RHYPER = TSDL_Keycode($20000007); {*< Extended key Right Hyper } {* * Valid key modifiers (possibly OR'd together). * - * \since This datatype is available since SDL 3.1.3. + * \since This datatype is available since SDL 3.2.0. } type PPSDL_Keymod = ^PSDL_Keymod; @@ -298,6 +314,7 @@ const SDL_KMOD_NONE = TSDL_Keymod($0000); {*< no modifier is applicable. } SDL_KMOD_LSHIFT = TSDL_Keymod($0001); {*< the left Shift key is down. } SDL_KMOD_RSHIFT = TSDL_Keymod($0002); {*< the right Shift key is down. } + SDL_KMOD_LEVEL5 = TSDL_Keymod($0004); {*< the Level 5 Shift key is down. } SDL_KMOD_LCTRL = TSDL_Keymod($0040); {*< the left Ctrl (Control) key is down. } SDL_KMOD_RCTRL = TSDL_Keymod($0080); {*< the right Ctrl (Control) key is down. } SDL_KMOD_LALT = TSDL_Keymod($0100); {*< the left Alt key is down. } From 4f60715e4659392593eb59cdce7ab142f4ca82a2 Mon Sep 17 00:00:00 2001 From: suve Date: Thu, 14 Aug 2025 19:44:10 +0200 Subject: [PATCH 6/7] Update SDL_events.inc to match SDL 3.2.20 --- tests/type-sizes.sh | 1 + units/SDL3.pas | 2 +- units/SDL_events.inc | 203 ++++++++++++++++++++++++------------------- 3 files changed, 117 insertions(+), 89 deletions(-) diff --git a/tests/type-sizes.sh b/tests/type-sizes.sh index 68ea865..5f3ccaa 100755 --- a/tests/type-sizes.sh +++ b/tests/type-sizes.sh @@ -163,6 +163,7 @@ for TYPENAME in \ SDL_QuitEvent \ SDL_Rect \ SDL_RendererLogicalPresentation \ + SDL_RenderEvent \ SDL_ScaleMode \ SDL_Scancode \ SDL_SensorEvent \ diff --git a/units/SDL3.pas b/units/SDL3.pas index 7698bad..9da114d 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -109,7 +109,7 @@ interface {$I SDL_pen.inc} // 3.1.6-prev {$I SDL_touch.inc} // 3.1.6-prev {$I SDL_camera.inc} // 3.1.6-prev -{$I SDL_events.inc} // 3.1.6-prev +{$I SDL_events.inc} // 3.2.20 {$I SDL_init.inc} // 3.2.20 {$I SDL_render.inc} // 3.1.6-prev {$I SDL_gpu.inc} // 3.2.0 diff --git a/units/SDL_events.inc b/units/SDL_events.inc index 4a887e7..2f2dc78 100644 --- a/units/SDL_events.inc +++ b/units/SDL_events.inc @@ -10,6 +10,30 @@ * # CategoryEvents * * Event queue management. + * + * It's extremely common--often required--that an app deal with SDL's event + * queue. Almost all useful information about interactions with the real world + * flow through here: the user interacting with the computer and app, hardware + * coming and going, the system changing in some way, etc. + * + * An app generally takes a moment, perhaps at the start of a new frame, to + * examine any events that have occured since the last time and process or + * ignore them. This is generally done by calling SDL_PollEvent() in a loop + * until it returns false (or, if using the main callbacks, events are + * provided one at a time in calls to SDL_AppEvent() before the next call to + * SDL_AppIterate(); in this scenario, the app does not call SDL_PollEvent() + * at all). + * + * There is other forms of control, too: SDL_PeepEvents() has more + * functionality at the cost of more complexity, and SDL_WaitEvent() can block + * the process until something interesting happens, which might be beneficial + * for certain types of programs on low-power hardware. One may also call + * SDL_AddEventWatch() to set a callback when new events arrive. + * + * The app is free to generate their own events, too: SDL_PushEvent allows the + * app to put events onto the queue for later retrieval; SDL_RegisterEvents + * can guarantee that these events have a type that isn't in use by other + * parts of the system. } { General keyboard/mouse/pen state definitions } @@ -17,7 +41,7 @@ {* * The types of events that can be delivered. * - * \since This enum is available since SDL 3.1.3. + * \since This enum is available since SDL 3.2.0. } type PPSDL_EventType = ^PSDL_EventType; @@ -73,7 +97,7 @@ const { Window events } { 0x200 was SDL_WINDOWEVENT, reserve the number for sdl2-compat } - { 0x201 was SDL_EVENT_SYSWM, reserve the number for sdl2-compat } + { 0x201 was SDL_SYSWMEVENT, reserve the number for sdl2-compat } SDL_EVENT_WINDOW_SHOWN = TSDL_EventType($202); {*< Window has been shown } SDL_EVENT_WINDOW_HIDDEN = TSDL_EventType(515); {*< Window has been hidden } SDL_EVENT_WINDOW_EXPOSED = TSDL_EventType(516); {*< Window has been exposed and should be redrawn, and can be redrawn directly from event watchers for this event } @@ -153,6 +177,7 @@ const SDL_EVENT_FINGER_DOWN = TSDL_EventType($700); SDL_EVENT_FINGER_UP = TSDL_EventType(1793); SDL_EVENT_FINGER_MOTION = TSDL_EventType(1794); + SDL_EVENT_FINGER_CANCELED = TSDL_EventType(1795); { 0x800, 0x801, and 0x802 were the Gesture events from SDL2. Do not reuse these values! sdl2-compat needs them! } @@ -220,7 +245,7 @@ const {* * Fields shared by every event * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } type PPSDL_CommonEvent = ^PSDL_CommonEvent; @@ -234,7 +259,7 @@ type {* * Display state change event data (event.display.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_DisplayEvent = ^PSDL_DisplayEvent; PSDL_DisplayEvent = ^TSDL_DisplayEvent; @@ -250,7 +275,7 @@ type {* * Window state change event data (event.window.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_WindowEvent = ^PSDL_WindowEvent; PSDL_WindowEvent = ^TSDL_WindowEvent; @@ -266,7 +291,7 @@ type {* * Keyboard device event structure (event.kdevice.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_KeyboardDeviceEvent = ^PSDL_KeyboardDeviceEvent; PSDL_KeyboardDeviceEvent = ^TSDL_KeyboardDeviceEvent; @@ -286,7 +311,7 @@ type * event scancode and modifiers directly from the keyboard layout, bypassing * SDL_HINT_KEYCODE_OPTIONS, by calling SDL_GetKeyFromScancode(). * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GetKeyFromScancode * \sa SDL_HINT_KEYCODE_OPTIONS @@ -314,7 +339,7 @@ type * will be inserted into the editing text. The length is the number of UTF-8 * characters that will be replaced by new typing. * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_TextEditingEvent = ^PSDL_TextEditingEvent; PSDL_TextEditingEvent = ^TSDL_TextEditingEvent; @@ -331,7 +356,7 @@ type {* * Keyboard IME candidates event structure (event.edit_candidates.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_TextEditingCandidatesEvent = ^PSDL_TextEditingCandidatesEvent; PSDL_TextEditingCandidatesEvent = ^TSDL_TextEditingCandidatesEvent; @@ -355,7 +380,7 @@ type * This event will never be delivered unless text input is enabled by calling * SDL_StartTextInput(). Text input is disabled by default! * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_StartTextInput * \sa SDL_StopTextInput @@ -373,7 +398,7 @@ type {* * Mouse device event structure (event.mdevice.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_MouseDeviceEvent = ^PSDL_MouseDeviceEvent; PSDL_MouseDeviceEvent = ^TSDL_MouseDeviceEvent; @@ -387,7 +412,7 @@ type {* * Mouse motion event structure (event.motion.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_MouseMotionEvent = ^PSDL_MouseMotionEvent; PSDL_MouseMotionEvent = ^TSDL_MouseMotionEvent; @@ -407,7 +432,7 @@ type {* * Mouse button event structure (event.button.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_MouseButtonEvent = ^PSDL_MouseButtonEvent; PSDL_MouseButtonEvent = ^TSDL_MouseButtonEvent; @@ -416,7 +441,7 @@ type reserved: cuint32; timestamp: cuint64; {*< In nanoseconds, populated using SDL_GetTicksNS() } windowID: TSDL_WindowID; {*< The window with mouse focus, if any } - which: TSDL_MouseID; {*< The mouse instance id, SDL_TOUCH_MOUSEID } + which: TSDL_MouseID; {*< The mouse instance id in relative mode, SDL_TOUCH_MOUSEID for touch events, or 0 } button: cuint8; {*< The mouse button index } down: Boolean; {*< true if the button is pressed } clicks: cuint8; {*< 1 for single-click, 2 for double-click, etc. } @@ -428,7 +453,7 @@ type {* * Mouse wheel event structure (event.wheel.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_MouseWheelEvent = ^PSDL_MouseWheelEvent; PSDL_MouseWheelEvent = ^TSDL_MouseWheelEvent; @@ -437,7 +462,7 @@ type reserved: cuint32; timestamp: cuint64; {*< In nanoseconds, populated using SDL_GetTicksNS() } windowID: TSDL_WindowID; {*< The window with mouse focus, if any } - which: TSDL_MouseID; {*< The mouse instance id, SDL_TOUCH_MOUSEID } + which: TSDL_MouseID; {*< The mouse instance id in relative mode or 0 } x: cfloat; {*< The amount scrolled horizontally, positive to the right and negative to the left } y: cfloat; {*< The amount scrolled vertically, positive away from the user and negative toward the user } direction: TSDL_MouseWheelDirection; {*< Set to one of the SDL_MOUSEWHEEL_* defines. When FLIPPED the values in X and Y will be opposite. Multiply by -1 to change them back } @@ -450,7 +475,7 @@ type {* * Joystick axis motion event structure (event.jaxis.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_JoyAxisEvent = ^PSDL_JoyAxisEvent; PSDL_JoyAxisEvent = ^TSDL_JoyAxisEvent; @@ -470,7 +495,7 @@ type {* * Joystick trackball motion event structure (event.jball.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_JoyBallEvent = ^PSDL_JoyBallEvent; PSDL_JoyBallEvent = ^TSDL_JoyBallEvent; @@ -490,7 +515,7 @@ type {* * Joystick hat position change event structure (event.jhat.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_JoyHatEvent = ^PSDL_JoyHatEvent; PSDL_JoyHatEvent = ^TSDL_JoyHatEvent; @@ -513,7 +538,7 @@ type {* * Joystick button event structure (event.jbutton.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_JoyButtonEvent = ^PSDL_JoyButtonEvent; PSDL_JoyButtonEvent = ^TSDL_JoyButtonEvent; @@ -534,7 +559,7 @@ type * SDL will send JOYSTICK_ADDED events for devices that are already plugged in * during SDL_Init. * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_GamepadDeviceEvent } @@ -550,7 +575,7 @@ type {* * Joystick battery level change event structure (event.jbattery.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_JoyBatteryEvent = ^PSDL_JoyBatteryEvent; PSDL_JoyBatteryEvent = ^TSDL_JoyBatteryEvent; @@ -566,7 +591,7 @@ type {* * Gamepad axis motion event structure (event.gaxis.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_GamepadAxisEvent = ^PSDL_GamepadAxisEvent; PSDL_GamepadAxisEvent = ^TSDL_GamepadAxisEvent; @@ -586,7 +611,7 @@ type {* * Gamepad button event structure (event.gbutton.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_GamepadButtonEvent = ^PSDL_GamepadButtonEvent; PSDL_GamepadButtonEvent = ^TSDL_GamepadButtonEvent; @@ -611,7 +636,7 @@ type * in during SDL_Init() and are recognized as gamepads. It will also send * events for joysticks that get gamepad mappings at runtime. * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. * * \sa SDL_JoyDeviceEvent } @@ -627,7 +652,7 @@ type {* * Gamepad touchpad event structure (event.gtouchpad.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_GamepadTouchpadEvent = ^PSDL_GamepadTouchpadEvent; PSDL_GamepadTouchpadEvent = ^TSDL_GamepadTouchpadEvent; @@ -646,7 +671,7 @@ type {* * Gamepad sensor event structure (event.gsensor.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_GamepadSensorEvent = ^PSDL_GamepadSensorEvent; PSDL_GamepadSensorEvent = ^TSDL_GamepadSensorEvent; @@ -663,7 +688,7 @@ type {* * Audio device event structure (event.adevice.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_AudioDeviceEvent = ^PSDL_AudioDeviceEvent; PSDL_AudioDeviceEvent = ^TSDL_AudioDeviceEvent; @@ -681,7 +706,7 @@ type {* * Camera device event structure (event.cdevice.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_CameraDeviceEvent = ^PSDL_CameraDeviceEvent; PSDL_CameraDeviceEvent = ^TSDL_CameraDeviceEvent; @@ -692,6 +717,20 @@ type which: TSDL_CameraID; {*< SDL_CameraID for the device being added or removed or changing } end; +{* + * Renderer event structure (event.render.*) + * + * \since This struct is available since SDL 3.2.0. + *} + PPSDL_RenderEvent = ^PSDL_RenderEvent; + PSDL_RenderEvent = ^TSDL_RenderEvent; + TSDL_RenderEvent = record + type_: TSDL_EventType; {*< SDL_EVENT_RENDER_TARGETS_RESET, SDL_EVENT_RENDER_DEVICE_RESET, SDL_EVENT_RENDER_DEVICE_LOST } + reserved: cuint32; + timestamp: cuint64; {*< In nanoseconds, populated using SDL_GetTicksNS() } + windowID: TSDL_WindowID; {*< The window containing the renderer in question. } + end; + {* * Touch finger event structure (event.tfinger.*) * @@ -709,12 +748,12 @@ type * report a touch outside of the window, which will also be outside of the * range. * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_TouchFingerEvent = ^PSDL_TouchFingerEvent; PSDL_TouchFingerEvent = ^TSDL_TouchFingerEvent; TSDL_TouchFingerEvent = record - type_: TSDL_EventType; {*< SDL_EVENT_FINGER_MOTION or SDL_EVENT_FINGER_DOWN or SDL_EVENT_FINGER_UP } + type_: TSDL_EventType; {*< SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_UP, SDL_EVENT_FINGER_MOTION, or SDL_EVENT_FINGER_CANCELED } reserved: cuint32; timestamp: cuint64; {*< In nanoseconds, populated using SDL_GetTicksNS() } touchID: TSDL_TouchID; {*< The touch device id } @@ -740,7 +779,7 @@ type * is there." The pen touching and lifting off from the tablet while not * leaving the area are handled by SDL_EVENT_PEN_DOWN and SDL_EVENT_PEN_UP. * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_PenProximityEvent = ^PSDL_PenProximityEvent; PSDL_PenProximityEvent = ^TSDL_PenProximityEvent; @@ -748,7 +787,7 @@ type type_: TSDL_EventType; {*< SDL_EVENT_PEN_PROXIMITY_IN or SDL_EVENT_PEN_PROXIMITY_OUT } reserved: cuint32; timestamp: cuint64; {*< In nanoseconds, populated using SDL_GetTicksNS() } - windowID: TSDL_WindowID; {*< The window with mouse focus, if any } + windowID: TSDL_WindowID; {*< The window with pen focus, if any } which: TSDL_PenID; {*< The pen instance id } end; @@ -761,7 +800,7 @@ type * `pen_state & SDL_PEN_INPUT_DOWN` to decide if a pen is "drawing" when * dealing with pen motion. * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_PenMotionEvent = ^PSDL_PenMotionEvent; PSDL_PenMotionEvent = ^TSDL_PenMotionEvent; @@ -782,7 +821,7 @@ type * These events come when a pen touches a surface (a tablet, etc), or lifts * off from one. * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_PenTouchEvent = ^PSDL_PenTouchEvent; PSDL_PenTouchEvent = ^TSDL_PenTouchEvent; @@ -805,7 +844,7 @@ type * This is for buttons on the pen itself that the user might click. The pen * itself pressing down to draw triggers a SDL_EVENT_PEN_DOWN event instead. * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_PenButtonEvent = ^PSDL_PenButtonEvent; PSDL_PenButtonEvent = ^TSDL_PenButtonEvent; @@ -828,7 +867,7 @@ type * You might get some of these events even if the pen isn't touching the * tablet. * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_PenAxisEvent = ^PSDL_PenAxisEvent; PSDL_PenAxisEvent = ^TSDL_PenAxisEvent; @@ -849,7 +888,7 @@ type * An event used to drop text or request a file open by the system * (event.drop.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_DropEvent = ^PSDL_DropEvent; PSDL_DropEvent = ^TSDL_DropEvent; @@ -868,7 +907,7 @@ type * An event triggered when the clipboard contents have changed * (event.clipboard.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_ClipboardEvent = ^PSDL_ClipboardEvent; PSDL_ClipboardEvent = ^TSDL_ClipboardEvent; @@ -884,7 +923,7 @@ type {* * Sensor event structure (event.sensor.*) * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_SensorEvent = ^PSDL_SensorEvent; PSDL_SensorEvent = ^TSDL_SensorEvent; @@ -900,7 +939,7 @@ type {* * The "quit requested" event * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_QuitEvent = ^PSDL_QuitEvent; PSDL_QuitEvent = ^TSDL_QuitEvent; @@ -919,7 +958,7 @@ type * the programmer; the only requirement is that '''type''' is a value obtained * from SDL_RegisterEvents(). * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } PPSDL_UserEvent = ^PSDL_UserEvent; PSDL_UserEvent = ^TSDL_UserEvent; @@ -939,7 +978,7 @@ type * The SDL_Event structure is the core of all event handling in SDL. SDL_Event * is a union of all event structures used in SDL. * - * \since This struct is available since SDL 3.1.3. + * \since This struct is available since SDL 3.2.0. } type PPSDL_Event = ^PSDL_Event; @@ -981,8 +1020,9 @@ type 32: (pmotion: TSDL_PenMotionEvent); {*< Pen motion event data } 33: (pbutton: TSDL_PenButtonEvent); {*< Pen button event data } 34: (paxis: TSDL_PenAxisEvent); {*< Pen axis event data } - 35: (drop: TSDL_DropEvent); {*< Drag and drop event data } - 36: (clipboard: TSDL_ClipboardEvent); {*< Clipboard event data } + 35: (render: TSDL_RenderEvent); {*< Render event data } + 36: (drop: TSDL_DropEvent); {*< Drag and drop event data } + 37: (clipboard: TSDL_ClipboardEvent); {*< Clipboard event data } { This is necessary for ABI compatibility between Visual C++ and GCC. Visual C++ will respect the push pack pragma and use 52 bytes (size of @@ -1019,11 +1059,9 @@ type * polling or waiting for events (e.g. you are filtering them), then you must * call SDL_PumpEvents() to force an event queue update. * - * \threadsafety This should only be run in the thread that initialized the - * video subsystem, and for extra safety, you should consider - * only doing those things on the main thread in any case. + * \threadsafety This function should only be called on the main thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_WaitEvent @@ -1034,7 +1072,7 @@ procedure SDL_PumpEvents; cdecl; {* * The type of action to request from SDL_PeepEvents(). * - * \since This enum is available since SDL 3.1.3. + * \since This enum is available since SDL 3.2.0. } type PPSDL_EventAction = ^PSDL_EventAction; @@ -1071,7 +1109,7 @@ type * \param numevents if action is SDL_ADDEVENT, the number of events to add * back to the event queue; if action is SDL_PEEKEVENT or * SDL_GETEVENT, the maximum number of events to retrieve. - * \param action action to take; see [[#action|Remarks]] for details. + * \param action action to take; see [Remarks](#remarks) for details. * \param minType minimum value of the event type to be considered; * SDL_EVENT_FIRST is a safe choice. * \param maxType maximum value of the event type to be considered; @@ -1081,7 +1119,7 @@ type * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PumpEvents @@ -1102,7 +1140,7 @@ function SDL_PeepEvents(events: PSDL_Event; numevents: cint; action: TSDL_EventA * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasEvents } @@ -1123,7 +1161,7 @@ function SDL_HasEvent(type_: cuint32): Boolean; cdecl; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_HasEvents } @@ -1152,7 +1190,7 @@ function SDL_HasEvents(minType: cuint32; maxType: cuint32): Boolean; cdecl; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_FlushEvents } @@ -1180,7 +1218,7 @@ procedure SDL_FlushEvent(type_: cuint32); cdecl; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_FlushEvent } @@ -1223,11 +1261,9 @@ procedure SDL_FlushEvents(minType: cuint32; maxType: cuint32); cdecl; * the queue, or nil. * \returns true if this got an event or false if there are none available. * - * \threadsafety This should only be run in the thread that initialized the - * video subsystem, and for extra safety, you should consider - * only doing those things on the main thread in any case. + * \threadsafety This function should only be called on the main thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PushEvent * \sa SDL_WaitEvent @@ -1250,11 +1286,9 @@ function SDL_PollEvent(event: PSDL_Event): Boolean; cdecl; * \returns true on success or false if there was an error while waiting for * events; call SDL_GetError() for more information. * - * \threadsafety This should only be run in the thread that initialized the - * video subsystem, and for extra safety, you should consider - * only doing those things on the main thread in any case. + * \threadsafety This function should only be called on the main thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PushEvent @@ -1283,11 +1317,9 @@ function SDL_WaitEvent(event: PSDL_Event): Boolean; cdecl; * \returns true if this got an event or false if the timeout elapsed without * any events available. * - * \threadsafety This should only be run in the thread that initialized the - * video subsystem, and for extra safety, you should consider - * only doing those things on the main thread in any case. + * \threadsafety This function should only be called on the main thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_PushEvent @@ -1322,7 +1354,7 @@ function SDL_WaitEventTimeout(event: PSDL_Event; timeoutMS: cint32): Boolean; cd * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PeepEvents * \sa SDL_PollEvent @@ -1355,8 +1387,11 @@ type TSDL_EventFilter = function (userdata: Pointer; event: PSDL_Event): Boolean; cdecl; {* - * Set up a filter to process all events before they change internal state and - * are posted to the internal event queue. + * Set up a filter to process all events before they are added to the internal + * event queue. + * + * If you just want to see events without modifying them or preventing them + * from being queued, you should use SDL_AddEventWatch() instead. * * If the filter function returns true when called, then the event will be * added to the internal queue. If it returns false, then the event will be @@ -1370,17 +1405,9 @@ type * interrupt signal (e.g. pressing Ctrl-C), it will be delivered to the * application at the next event poll. * - * There is one caveat when dealing with the SDL_QuitEvent event type. The - * event filter is only called when the window manager desires to close the - * application window. If the event filter returns 1, then the window will be - * closed, otherwise the window will remain open if possible. - * * Note: Disabled events never make it to the event filter function; see * SDL_SetEventEnabled(). * - * Note: If you just want to inspect events without filtering, you should use - * SDL_AddEventWatch() instead. - * * Note: Events pushed onto the queue with SDL_PushEvent() get passed through * the event filter, but events pushed onto the queue with SDL_PeepEvents() do * not. @@ -1390,7 +1417,7 @@ type * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch * \sa SDL_SetEventEnabled @@ -1414,7 +1441,7 @@ procedure SDL_SetEventFilter(filter: TSDL_EventFilter; userdata: Pointer); cdecl * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetEventFilter } @@ -1446,7 +1473,7 @@ function SDL_GetEventFilter(filter: PSDL_EventFilter; userdata: PPointer): Boole * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_RemoveEventWatch * \sa SDL_SetEventFilter @@ -1465,7 +1492,7 @@ function SDL_AddEventWatch(filter: TSDL_EventFilter; userdata: Pointer): Boolean * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_AddEventWatch } @@ -1485,7 +1512,7 @@ procedure SDL_RemoveEventWatch(filter: TSDL_EventFilter; userdata: Pointer); cde * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_GetEventFilter * \sa SDL_SetEventFilter @@ -1501,7 +1528,7 @@ procedure SDL_FilterEvents(filter: TSDL_EventFilter; userdata: Pointer); cdecl; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_EventEnabled } @@ -1516,7 +1543,7 @@ procedure SDL_SetEventEnabled(type_: cuint32; enabled: Boolean); cdecl; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_SetEventEnabled } @@ -1533,7 +1560,7 @@ function SDL_EventEnabled(type_: cuint32): Boolean; cdecl; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PushEvent } @@ -1548,7 +1575,7 @@ function SDL_RegisterEvents(numevents: cint): cuint32; cdecl; * * \threadsafety It is safe to call this function from any thread. * - * \since This function is available since SDL 3.1.3. + * \since This function is available since SDL 3.2.0. * * \sa SDL_PollEvent * \sa SDL_WaitEvent From bcc42c73bec7c0fb458dec5ae1e1594af1e43305 Mon Sep 17 00:00:00 2001 From: suve Date: Thu, 14 Aug 2025 19:57:45 +0200 Subject: [PATCH 7/7] Update SDL_pen.inc to match SDL 3.2.20 --- units/SDL3.pas | 2 +- units/SDL_pen.inc | 22 +++++++++++++++++++--- 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/units/SDL3.pas b/units/SDL3.pas index 9da114d..c9e429e 100644 --- a/units/SDL3.pas +++ b/units/SDL3.pas @@ -106,8 +106,8 @@ interface {$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_pen.inc} // 3.2.20 {$I SDL_camera.inc} // 3.1.6-prev {$I SDL_events.inc} // 3.2.20 {$I SDL_init.inc} // 3.2.20 diff --git a/units/SDL_pen.inc b/units/SDL_pen.inc index e8f8401..2037609 100644 --- a/units/SDL_pen.inc +++ b/units/SDL_pen.inc @@ -32,18 +32,34 @@ * consistent as long as SDL can recognize a tool to be the same pen; but if a * pen physically leaves the area and returns, it might get a new ID. * - * \since This datatype is available since SDL 3.1.3. + * \since This datatype is available since SDL 3.2.0. } type PPSDL_PenID = ^PSDL_PenID; PSDL_PenID = ^TSDL_PenID; TSDL_PenID = cuint32; +const + {* + * The SDL_MouseID for mouse events simulated with pen input. + * + * \since This macro is available since SDL 3.2.0. + *} + SDL_PEN_MOUSEID = TSDL_MouseID(-2); + + {* + * The SDL_TouchID for touch events simulated with pen input. + * + * \since This macro is available since SDL 3.2.0. + *} + SDL_PEN_TOUCHID = TSDL_TouchID(-2); + {* * Pen input flags, as reported by various pen events' `pen_state` field. * - * \since This datatype is available since SDL 3.1.3. + * \since This datatype is available since SDL 3.2.0. } +type PPSDL_PenInputFlags = ^PSDL_PenInputFlags; PSDL_PenInputFlags = ^TSDL_PenInputFlags; TSDL_PenInputFlags = cuint32; @@ -70,7 +86,7 @@ const * * `SDL_sinf(xtilt * SDL_PI_F / 180.0)`. * - * \since This enum is available since SDL 3.1.3 + * \since This enum is available since SDL 3.2.0. } type PPSDL_PenAxis = ^PSDL_PenAxis;