Add time and realtime clock functions

Adds functions to query the system's realtime clock, convert time intervals to/from a calendar date and time in either UTC or the local time, and perform time related calculations.

An SDL_Time type (a time interval represented in nanoseconds), and SDL_DateTime struct (broken down calendar date and time) were added to facilitate this functionality.

Querying the system time results in a value expressed in nanoseconds since the Unix epoch (Jan 1, 1970) in UTC +0000. Conversions to and from the various platform epochs and units are performed when required.

Any direct handling of timezones and DST were intentionally avoided. The offset from UTC is provided when converting from UTC to a local time by calculating the difference between the original UTC and the resulting local time, but no other timezone or DST information is used.

The preferred date formatting and 12/24 hour time for the system locale can be retrieved via global preferences.

Helper functions for obtaining the day of week or day or year for calendar date, and getting the number of days in a month in a given year are provided for convenience. These are simple, but useful for performing various time related calculations.

An automated test for time conversion is included, as is a simple standalone test to display the current system date and time onscreen along with a calendar, the rendering of which demonstrates the use of the utility functions (press up/down to increment or decrement the current month, and keys 1-5 to change the date and time formats).

src/dynapi/SDL_dynapi.sym

@@ -92,6 +92,7 @@ SDL3_0.0.0 {
     SDL_CreateWindowWithProperties;
     SDL_CursorVisible;
     SDL_DXGIGetOutputInfo;
+    SDL_DateTimeToTime;
     SDL_DelEventWatch;
     SDL_DelHintCallback;
     SDL_Delay;
@@ -128,8 +129,6 @@ SDL3_0.0.0 {
     SDL_EnumerateStorageDirectory;
     SDL_Error;
     SDL_EventEnabled;
-    SDL_FileTimeFromWindows;
-    SDL_FileTimeToWindows;
     SDL_FillSurfaceRect;
     SDL_FillSurfaceRects;
     SDL_FilterEvents;
@@ -202,8 +201,12 @@ SDL3_0.0.0 {
     SDL_GetCurrentDisplayOrientation;
     SDL_GetCurrentRenderOutputSize;
     SDL_GetCurrentThreadID;
+    SDL_GetCurrentTime;
     SDL_GetCurrentVideoDriver;
     SDL_GetCursor;
+    SDL_GetDayOfWeek;
+    SDL_GetDayOfYear;
+    SDL_GetDaysInMonth;
     SDL_GetDefaultAssertionHandler;
     SDL_GetDefaultCursor;
     SDL_GetDesktopDisplayMode;
@@ -781,6 +784,9 @@ SDL3_0.0.0 {
     SDL_TellIO;
     SDL_TextInputActive;
     SDL_TextInputShown;
+    SDL_TimeFromWindows;
+    SDL_TimeToDateTime;
+    SDL_TimeToWindows;
     SDL_TryLockMutex;
     SDL_TryLockRWLockForReading;
     SDL_TryLockRWLockForWriting;

src/dynapi/SDL_dynapi_overrides.h

@@ -117,6 +117,7 @@
 #define SDL_CreateWindowWithProperties SDL_CreateWindowWithProperties_REAL
 #define SDL_CursorVisible SDL_CursorVisible_REAL
 #define SDL_DXGIGetOutputInfo   SDL_DXGIGetOutputInfo_REAL
+#define SDL_DateTimeToTime SDL_DateTimeToTime_REAL
 #define SDL_DelEventWatch SDL_DelEventWatch_REAL
 #define SDL_DelHintCallback SDL_DelHintCallback_REAL
 #define SDL_Delay SDL_Delay_REAL
@@ -153,8 +154,6 @@
 #define SDL_EnumerateStorageDirectory SDL_EnumerateStorageDirectory_REAL
 #define SDL_Error SDL_Error_REAL
 #define SDL_EventEnabled SDL_EventEnabled_REAL
-#define SDL_FileTimeFromWindows SDL_FileTimeFromWindows_REAL
-#define SDL_FileTimeToWindows SDL_FileTimeToWindows_REAL
 #define SDL_FillSurfaceRect SDL_FillSurfaceRect_REAL
 #define SDL_FillSurfaceRects SDL_FillSurfaceRects_REAL
 #define SDL_FilterEvents SDL_FilterEvents_REAL
@@ -227,8 +226,12 @@
 #define SDL_GetCurrentDisplayOrientation SDL_GetCurrentDisplayOrientation_REAL
 #define SDL_GetCurrentRenderOutputSize SDL_GetCurrentRenderOutputSize_REAL
 #define SDL_GetCurrentThreadID SDL_GetCurrentThreadID_REAL
+#define SDL_GetCurrentTime SDL_GetCurrentTime_REAL
 #define SDL_GetCurrentVideoDriver SDL_GetCurrentVideoDriver_REAL
 #define SDL_GetCursor SDL_GetCursor_REAL
+#define SDL_GetDayOfWeek SDL_GetDayOfWeek_REAL
+#define SDL_GetDayOfYear SDL_GetDayOfYear_REAL
+#define SDL_GetDaysInMonth SDL_GetDaysInMonth_REAL
 #define SDL_GetDefaultAssertionHandler SDL_GetDefaultAssertionHandler_REAL
 #define SDL_GetDefaultCursor SDL_GetDefaultCursor_REAL
 #define SDL_GetDesktopDisplayMode SDL_GetDesktopDisplayMode_REAL
@@ -805,6 +808,9 @@
 #define SDL_TellIO SDL_TellIO_REAL
 #define SDL_TextInputActive SDL_TextInputActive_REAL
 #define SDL_TextInputShown SDL_TextInputShown_REAL
+#define SDL_TimeFromWindows SDL_TimeFromWindows_REAL
+#define SDL_TimeToDateTime SDL_TimeToDateTime_REAL
+#define SDL_TimeToWindows SDL_TimeToWindows_REAL
 #define SDL_TryLockMutex SDL_TryLockMutex_REAL
 #define SDL_TryLockRWLockForReading SDL_TryLockRWLockForReading_REAL
 #define SDL_TryLockRWLockForWriting SDL_TryLockRWLockForWriting_REAL

src/dynapi/SDL_dynapi_procs.h

@@ -155,6 +155,7 @@ SDL_DYNAPI_PROC(int,SDL_CreateWindowAndRenderer,(int a, int b, Uint32 c, SDL_Win
 SDL_DYNAPI_PROC(SDL_Window*,SDL_CreateWindowWithProperties,(SDL_PropertiesID a),(a),return)
 SDL_DYNAPI_PROC(SDL_bool,SDL_CursorVisible,(void),(),return)
 SDL_DYNAPI_PROC(SDL_bool,SDL_DXGIGetOutputInfo,(SDL_DisplayID a, int *b, int *c),(a,b,c),return)
+SDL_DYNAPI_PROC(int,SDL_DateTimeToTime,(const SDL_DateTime *a, SDL_Time *b),(a,b),return)
 SDL_DYNAPI_PROC(void,SDL_DelEventWatch,(SDL_EventFilter a, void *b),(a,b),)
 SDL_DYNAPI_PROC(void,SDL_DelHintCallback,(const char *a, SDL_HintCallback b, void *c),(a,b,c),)
 SDL_DYNAPI_PROC(void,SDL_Delay,(Uint32 a),(a),)
@@ -191,8 +192,6 @@ SDL_DYNAPI_PROC(int,SDL_EnumerateProperties,(SDL_PropertiesID a, SDL_EnumeratePr
 SDL_DYNAPI_PROC(int,SDL_EnumerateStorageDirectory,(SDL_Storage *a, const char *b, SDL_EnumerateDirectoryCallback c, void *d),(a,b,c,d),return)
 SDL_DYNAPI_PROC(int,SDL_Error,(SDL_errorcode a),(a),return)
 SDL_DYNAPI_PROC(SDL_bool,SDL_EventEnabled,(Uint32 a),(a),return)
-SDL_DYNAPI_PROC(SDL_FileTime,SDL_FileTimeFromWindows,(Uint32 a, Uint32 b),(a,b),return)
-SDL_DYNAPI_PROC(void,SDL_FileTimeToWindows,(Sint64 a, Uint32 *b, Uint32 *c),(a,b,c),)
 SDL_DYNAPI_PROC(int,SDL_FillSurfaceRect,(SDL_Surface *a, const SDL_Rect *b, Uint32 c),(a,b,c),return)
 SDL_DYNAPI_PROC(int,SDL_FillSurfaceRects,(SDL_Surface *a, const SDL_Rect *b, int c, Uint32 d),(a,b,c,d),return)
 SDL_DYNAPI_PROC(void,SDL_FilterEvents,(SDL_EventFilter a, void *b),(a,b),)
@@ -265,8 +264,12 @@ SDL_DYNAPI_PROC(const SDL_DisplayMode*,SDL_GetCurrentDisplayMode,(SDL_DisplayID
 SDL_DYNAPI_PROC(SDL_DisplayOrientation,SDL_GetCurrentDisplayOrientation,(SDL_DisplayID a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_GetCurrentRenderOutputSize,(SDL_Renderer *a, int *b, int *c),(a,b,c),return)
 SDL_DYNAPI_PROC(SDL_ThreadID,SDL_GetCurrentThreadID,(void),(),return)
+SDL_DYNAPI_PROC(int,SDL_GetCurrentTime,(SDL_Time *a),(a),return)
 SDL_DYNAPI_PROC(const char*,SDL_GetCurrentVideoDriver,(void),(),return)
 SDL_DYNAPI_PROC(SDL_Cursor*,SDL_GetCursor,(void),(),return)
+SDL_DYNAPI_PROC(int,SDL_GetDayOfWeek,(int a, int b, int c),(a,b,c),return)
+SDL_DYNAPI_PROC(int,SDL_GetDayOfYear,(int a, int b, int c),(a,b,c),return)
+SDL_DYNAPI_PROC(int,SDL_GetDaysInMonth,(int a, int b),(a,b),return)
 SDL_DYNAPI_PROC(SDL_AssertionHandler,SDL_GetDefaultAssertionHandler,(void),(),return)
 SDL_DYNAPI_PROC(SDL_Cursor*,SDL_GetDefaultCursor,(void),(),return)
 SDL_DYNAPI_PROC(const SDL_DisplayMode*,SDL_GetDesktopDisplayMode,(SDL_DisplayID a),(a),return)
@@ -825,6 +828,9 @@ SDL_DYNAPI_PROC(int,SDL_SyncWindow,(SDL_Window *a),(a),return)
 SDL_DYNAPI_PROC(Sint64,SDL_TellIO,(SDL_IOStream *a),(a),return)
 SDL_DYNAPI_PROC(SDL_bool,SDL_TextInputActive,(void),(),return)
 SDL_DYNAPI_PROC(SDL_bool,SDL_TextInputShown,(void),(),return)
+SDL_DYNAPI_PROC(SDL_Time,SDL_TimeFromWindows,(Uint32 a, Uint32 b),(a,b),return)
+SDL_DYNAPI_PROC(int,SDL_TimeToDateTime,(SDL_Time a, SDL_DateTime *b, SDL_bool c),(a,b,c),return)
+SDL_DYNAPI_PROC(void,SDL_TimeToWindows,(SDL_Time a, Uint32 *b, Uint32 *c),(a,b,c),)
 SDL_DYNAPI_PROC(int,SDL_TryLockMutex,(SDL_Mutex *a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_TryLockRWLockForReading,(SDL_RWLock *a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_TryLockRWLockForWriting,(SDL_RWLock *a),(a),return)