Update SDL_pen.inc to 3.4.4

Author: Free-Pascal-meets-SDL-Website

units/SDL3.pas

@@ -107,7 +107,7 @@ interface
 {$I SDL_gamepad.inc}                      // 3.4.4
 {$I SDL_haptic.inc}                       // 3.4.4
 {$I SDL_touch.inc}                        // 3.4.4
-{$I SDL_pen.inc}                          // 3.2.20
+{$I SDL_pen.inc}                          // 3.4.4
 {$I SDL_camera.inc}                       // 3.4.4
 {$I SDL_events.inc}                       // 3.2.20
 {$I SDL_init.inc}                         // 3.2.20

units/SDL_pen.inc

@@ -15,12 +15,37 @@
  * handling, e.g., for input and drawing tablets or suitably equipped mobile /
  * tablet devices.
  *
- * To get started with pens, simply handle SDL_EVENT_PEN_* events. When a pen
- * starts providing input, SDL will assign it a unique SDL_PenID, which will
- * remain for the life of the process, as long as the pen stays connected.
+ * To get started with pens, simply handle pen events:
+ *
+ * - SDL_EVENT_PEN_PROXIMITY_IN, SDL_EVENT_PEN_PROXIMITY_OUT
+ *   (SDL_PenProximityEvent)
+ * - SDL_EVENT_PEN_DOWN, SDL_EVENT_PEN_UP (SDL_PenTouchEvent)
+ * - SDL_EVENT_PEN_MOTION (SDL_PenMotionEvent)
+ * - SDL_EVENT_PEN_BUTTON_DOWN, SDL_EVENT_PEN_BUTTON_UP (SDL_PenButtonEvent)
+ * - SDL_EVENT_PEN_AXIS (SDL_PenAxisEvent)
  *
  * Pens may provide more than simple touch input; they might have other axes,
  * such as pressure, tilt, rotation, etc.
+ *
+ * When a pen starts providing input, SDL will assign it a unique SDL_PenID,
+ * which will remain for the life of the process, as long as the pen stays
+ * connected. A pen leaving proximity (being taken far enough away from the
+ * digitizer tablet that it no longer reponds) and then coming back should
+ * fire proximity events, but the SDL_PenID should remain consistent.
+ * Unplugging the digitizer and reconnecting may cause future input to have a
+ * new SDL_PenID, as SDL may not know that this is the same hardware.
+ *
+ * Please note that various platforms vary wildly in how (and how well) they
+ * support pen input. If your pen supports some piece of functionality but SDL
+ * doesn't seem to, it might actually be the operating system's fault. For
+ * example, some platforms can manage multiple devices at the same time, but
+ * others will make any connected pens look like a single logical device, much
+ * how all USB mice connected to a computer will move the same system cursor.
+ * Other platforms might not support pen buttons, or the distance axis, etc.
+ * Very few platforms can even report _what_ functionality the pen supports in
+ * the first place, so best practices is to either build UI to let the user
+ * configure their pens, or be prepared to handle new functionality for a pen
+ * the first time an event is reported.
   }
 
 {*
@@ -30,7 +55,12 @@
  *
  * These show up in pen events when SDL sees input from them. They remain
  * consistent as long as SDL can recognize a tool to be the same pen; but if a
- * pen physically leaves the area and returns, it might get a new ID.
+ * pen's digitizer table is physically detached from the computer, it might
+ * get a new ID when reconnected, as SDL won't know it's the same device.
+ *
+ * These IDs are only stable within a single run of a program; the next time a
+ * program is run, the pen's ID will likely be different, even if the hardware
+ * hasn't been disconnected, etc.
  *
  * \since This datatype is available since SDL 3.2.0.
   }
@@ -72,6 +102,7 @@ const
   SDL_PEN_INPUT_BUTTON_4  = TSDL_PenInputFlags(1 shl 4);    {*< button 4 is pressed  }
   SDL_PEN_INPUT_BUTTON_5  = TSDL_PenInputFlags(1 shl 5);    {*< button 5 is pressed  }
   SDL_PEN_INPUT_ERASER_TIP  = TSDL_PenInputFlags(1 shl 30); {*< eraser tip is used  }
+  SDL_PEN_INPUT_IN_PROXIMITY = TSDL_PenInputFlags(1 shl 31); {*< pen is in proximity (since SDL 3.4.0)  }
 
  {*
  * Pen axis indices.
@@ -102,3 +133,29 @@ const
   SDL_PEN_AXIS_TANGENTIAL_PRESSURE  = TSDL_PenAxis(6);  {*< Pressure from squeezing the pen ("barrel pressure").  }
   SDL_PEN_AXIS_COUNT  = TSDL_PenAxis(7);                {*< Total known pen axis types in this version of SDL. This number may grow in future releases!  }
 
+{*
+  * An enum that describes the type of a pen device.
+  *
+  * A "direct" device is a pen that touches a graphic display (like an Apple
+  * Pencil on an iPad's screen). "Indirect" devices touch an
+  external tablet
+  * surface that is connected to the machine but is not a display (like a
+  * lower-end Wacom tablet connected over USB).
+  *
+  * Apps may use this information to decide if they should draw a cursor; if
+  * the pen is touching the screen directly, a cursor doesn't make sense and
+  * can be in the way, but becomes necessary for indirect devices to know where
+  * on the display they are interacting.
+  *
+  * \since This enum is available since SDL 3.4.0.
+  }
+type
+  PPSDL_PenDeviceType = ^PSDL_PenDeviceType;
+  PSDL_PenDeviceType = ^TSDL_PenDeviceType;
+  TSDL_PenDeviceType = type Integer;
+const
+  SDL_PEN_DEVICE_TYPE_INVALID = TSDL_PenDeviceType(-1); {*< Not a valid pen device.  }
+  SDL_PEN_DEVICE_TYPE_UNKNOWN = TSDL_PenDeviceType(0);  {*< Don't know specifics of this pen.  }
+  SDL_PEN_DEVICE_TYPE_DIRECT = TSDL_PenDeviceType(1);   {*< Pen touches display.  }
+  SDL_PEN_DEVICE_TYPE_INDIRECT = TSDL_PenDeviceType(2); {*< Pen touches something that isn't the display.  }
+