Update SDL_touch.inc to 3.4.4

Author: Free-Pascal-meets-SDL-Website

units/SDL3.pas

@@ -106,7 +106,7 @@ interface
 {$I SDL_joystick.inc}                     // 3.4.4
 {$I SDL_gamepad.inc}                      // 3.2.0
 {$I SDL_haptic.inc}                       // 3.2.0
-{$I SDL_touch.inc}                        // 3.1.6-prev
+{$I SDL_touch.inc}                        // 3.4.4
 {$I SDL_pen.inc}                          // 3.2.20
 {$I SDL_camera.inc}                       // 3.1.6-prev
 {$I SDL_events.inc}                       // 3.2.20

units/SDL_touch.inc

@@ -7,20 +7,59 @@
 }
 
 {*
- * # CategoryTouch
- *
- * SDL touch management.
+  * # CategoryTouch
+  *
+  * SDL offers touch input, on platforms that support it. It can manage
+  * multiple touch devices and track multiple fingers on those devices.
+  *
+  * Touches are mostly dealt with through the event system, in the
+  * SDL_EVENT_FINGER_DOWN, SDL_EVENT_FINGER_MOTION, and SDL_EVENT_FINGER_UP
+  * events, but there are also functions to query for hardware details, etc.
+  *
+  * The touch system, by default, will also send virtual mouse events; this can
+  * be useful for making a some desktop apps work on a phone without
+  * significant changes. For apps that care about mouse and touch input
+  * separately, they should ignore mouse events that have a `which` field of
+  * SDL_TOUCH_MOUSEID.
   }
 
+{
+* A unique ID for a touch device.
+*
+* This ID is valid for the time the device is connected to the system, and is
+* never reused for the lifetime of the application.
+*
+* The value 0 is an invalid ID.
+*
+* \since This datatype is available since SDL 3.2.0.
+}
 type
   PPSDL_TouchID = ^PSDL_TouchID;
   PSDL_TouchID = ^TSDL_TouchID;
   TSDL_TouchID = cuint64;
 
+{
+* A unique ID for a single finger on a touch device.
+*
+* This ID is valid for the time the finger (stylus, etc) is touching and will
+* be unique for all fingers currently in contact, so this ID tracks the
+* lifetime of a single continuous touch. This value may represent an index, a
+* pointer, or some other unique ID, depending on the platform.
+*
+* The value 0 is an invalid ID.
+*
+* \since This datatype is available since SDL 3.2.0.
+}
+type
   PPSDL_FingerID = ^PSDL_FingerID;
   PSDL_FingerID = ^TSDL_FingerID;
   TSDL_FingerID = cuint64;
 
+{
+* An enum that describes the type of a touch device.
+*
+* \since This enum is available since SDL 3.2.0.
+}
 type
   PPSDL_TouchDeviceType = ^PSDL_TouchDeviceType;
   PSDL_TouchDeviceType = ^TSDL_TouchDeviceType;
@@ -38,7 +77,7 @@ const
  * contact with the touch device (so a "touch" can be a "multitouch," in
  * reality), and this struct reports details of the specific fingers.
  *
- * \since This struct is available since SDL 3.1.3.
+ * \since This struct is available since SDL 3.2.0.
  *
  * \sa SDL_GetTouchFingers
   }
@@ -53,11 +92,19 @@ type
     end;
 
 { #todo : SDL3-for-Pascal: Translate macro }
-{ Used as the device ID for mouse events simulated with touch input  }
+{
+* The SDL_MouseID for mouse events simulated with touch input.
+*
+* \since This macro is available since SDL 3.2.0.
+}
 { #define SDL_TOUCH_MOUSEID ((SDL_MouseID)-1) }
 
 { #todo : SDL3-for-Pascal: Translate macro }
-{ Used as the SDL_TouchID for touch events simulated with mouse input  }
+{
+* The SDL_TouchID for touch events simulated with mouse input.
+*
+* \since This macro is available since SDL 3.2.0.
+}
 { #define SDL_MOUSE_TOUCHID ((SDL_TouchID)-1) }
 
 {*
@@ -73,7 +120,7 @@ type
  *          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.
+ * \since This function is available since SDL 3.2.0.
   }
 function SDL_GetTouchDevices(count: pcint): PSDL_TouchID; cdecl;
   external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetTouchDevices' {$ENDIF} {$ENDIF};
@@ -85,7 +132,7 @@ function SDL_GetTouchDevices(count: pcint): PSDL_TouchID; cdecl;
  * \returns touch device name, or nil 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.
   }
 function SDL_GetTouchDeviceName(touchID: TSDL_TouchID): PAnsiChar; cdecl;
   external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetTouchDeviceName' {$ENDIF} {$ENDIF};
@@ -96,7 +143,7 @@ function SDL_GetTouchDeviceName(touchID: TSDL_TouchID): PAnsiChar; cdecl;
  * \param touchID the ID of a touch device.
  * \returns touch device type.
  *
- * \since This function is available since SDL 3.1.3.
+ * \since This function is available since SDL 3.2.0.
   }
 function SDL_GetTouchDeviceType(touchID: TSDL_TouchID): TSDL_TouchDeviceType; cdecl;
   external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetTouchDeviceType' {$ENDIF} {$ENDIF};
@@ -112,7 +159,7 @@ function SDL_GetTouchDeviceType(touchID: TSDL_TouchID): TSDL_TouchDeviceType; cd
  *          allocation that should be freed with SDL_free() when it is no
  *          longer needed.
  *
- * \since This function is available since SDL 3.1.3.
+ * \since This function is available since SDL 3.2.0.
   }
 function SDL_GetTouchFingers(touchID: TSDL_TouchID; count: pcint):PPSDL_Finger; cdecl;
   external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetTouchFingers' {$ENDIF} {$ENDIF};