Update SDL_power.inc to 3.4.2

Author: Free-Pascal-meets-SDL-Website

units/SDL3.pas

@@ -96,7 +96,7 @@ interface
 {$I SDL_video.inc}                        // 3.4.2
 {$I SDL_timer.inc}                        // 3.2.20
 {$I SDL_error.inc}                        // 3.4.2
-{$I SDL_power.inc}                        // 3.1.6-prev
+{$I SDL_power.inc}                        // 3.4.2
 {$I SDL_audio.inc}                        // 3.1.6-prev
 {$I SDL_sensor.inc}                       // 3.1.6-prev
 {$I SDL_scancode.inc}                     // 3.1.6-prev

units/SDL_power.inc

@@ -10,21 +10,30 @@
  * # CategoryPower
  *
  * SDL power management routines.
+ *
+ * There is a single function in this category: SDL_GetPowerInfo().
+ *
+ * This function is useful for games on the go. This allows an app to know if
+ * it's running on a draining battery, which can be useful if the app wants to
+ * reduce processing, or perhaps framerate, to extend the duration of the
+ * battery's charge. Perhaps the app just wants to show a battery meter when
+ * fullscreen, or alert the user when the power is getting extremely low, so
+ * they can save their game.
   }
 
 {*
  * The basic state for the system's power supply.
  *
  * These are results returned by SDL_GetPowerInfo().
  *
- * \since This enum is available since SDL 3.1.3
+ * \since This enum is available since SDL 3.2.0
   }
 type
   PPSDL_PowerState = ^PSDL_PowerState;
   PSDL_PowerState = ^TSDL_PowerState;
   TSDL_PowerState = type Integer;
 const
-  SDL_POWERSTATE_ERROR = -1;                         {*< error determining power status  }
+  SDL_POWERSTATE_ERROR = TSDL_PowerState(-1);        {*< error determining power status  }
   SDL_POWERSTATE_UNKNOWN  = TSDL_PowerState(0);      {*< cannot determine power status  }
   SDL_POWERSTATE_ON_BATTERY  = TSDL_PowerState(1);   {*< Not plugged in, running on the battery  }
   SDL_POWERSTATE_NO_BATTERY  = TSDL_PowerState(2);   {*< Plugged in, no battery available  }
@@ -47,17 +56,23 @@ const
  * It's possible a platform can only report battery percentage or time left
  * but not both.
  *
- * \param seconds a Pointer filled in with the seconds of battery life left,
- *                or nil to ignore. This will be filled in with -1 if we
+ * On some platforms, retrieving power supply details might be expensive. If
+ * you want to display continuous status you could call this function every
+ * minute or so.
+ *
+ * \param seconds a pointer filled in with the seconds of battery life left,
+ *                or NULL to ignore. This will be filled in with -1 if we
  *                can't determine a value or there is no battery.
- * \param percent a Pointer filled in with the percentage of battery life
- *                left, between 0 and 100, or nil to ignore. This will be
- *                filled in with -1 we can't determine a value or there is no
- *                battery.
+ * \param percent a pointer filled in with the percentage of battery life
+ *                left, between 0 and 100, or NULL to ignore. This will be
+ *                filled in with -1 when we can't determine a value or there
+ *                is no battery.
  * \returns the current battery state or `SDL_POWERSTATE_ERROR` 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_GetPowerInfo(seconds: pcint; percent: pcint): TSDL_PowerState; cdecl;
   external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetPowerInfo' {$ENDIF} {$ENDIF};