Atlas - SDL_time.h
Home / ext / SDL / include / SDL3
Lines: 1 | Size: 8739 bytes
[Download] [Show on GitHub] [Search similar files] [Raw] [Raw (proxy)] 
[FILE BEGIN]
1/*
2Simple DirectMedia Layer
3Copyright (C) 1997-2026 Sam Lantinga <[email protected]>
4
5This software is provided 'as-is', without any express or implied
6warranty.  In no event will the authors be held liable for any damages
7arising from the use of this software.
8
9Permission is granted to anyone to use this software for any purpose,
10including commercial applications, and to alter it and redistribute it
11freely, subject to the following restrictions:
12
131. The origin of this software must not be misrepresented; you must not
14   claim that you wrote the original software. If you use this software
15   in a product, an acknowledgment in the product documentation would be
16   appreciated but is not required.
172. Altered source versions must be plainly marked as such, and must not be
18   misrepresented as being the original software.
193. This notice may not be removed or altered from any source distribution.
20*/
21
22#ifndef SDL_time_h_
23#define SDL_time_h_
24
25/**
26 * # CategoryTime
27 *
28 * SDL realtime clock and date/time routines.
29 *
30 * There are two data types that are used in this category: SDL_Time, which
31 * represents the nanoseconds since a specific moment (an "epoch"), and
32 * SDL_DateTime, which breaks time down into human-understandable components:
33 * years, months, days, hours, etc.
34 *
35 * Much of the functionality is involved in converting those two types to
36 * other useful forms.
37 */
38
39#include <SDL3/SDL_error.h>
40#include <SDL3/SDL_stdinc.h>
41
42#include <SDL3/SDL_begin_code.h>
43/* Set up for C function definitions, even when using C++ */
44#ifdef __cplusplus
45extern "C" {
46#endif
47
48/**
49 * A structure holding a calendar date and time broken down into its
50 * components.
51 *
52 * \since This struct is available since SDL 3.2.0.
53 */
54typedef struct SDL_DateTime
55{
56    int year;                  /**< Year */
57    int month;                 /**< Month [01-12] */
58    int day;                   /**< Day of the month [01-31] */
59    int hour;                  /**< Hour [0-23] */
60    int minute;                /**< Minute [0-59] */
61    int second;                /**< Seconds [0-60] */
62    int nanosecond;            /**< Nanoseconds [0-999999999] */
63    int day_of_week;           /**< Day of the week [0-6] (0 being Sunday) */
64    int utc_offset;            /**< Seconds east of UTC */
65} SDL_DateTime;
66
67/**
68 * The preferred date format of the current system locale.
69 *
70 * \since This enum is available since SDL 3.2.0.
71 *
72 * \sa SDL_GetDateTimeLocalePreferences
73 */
74typedef enum SDL_DateFormat
75{
76    SDL_DATE_FORMAT_YYYYMMDD = 0, /**< Year/Month/Day */
77    SDL_DATE_FORMAT_DDMMYYYY = 1, /**< Day/Month/Year */
78    SDL_DATE_FORMAT_MMDDYYYY = 2  /**< Month/Day/Year */
79} SDL_DateFormat;
80
81/**
82 * The preferred time format of the current system locale.
83 *
84 * \since This enum is available since SDL 3.2.0.
85 *
86 * \sa SDL_GetDateTimeLocalePreferences
87 */
88typedef enum SDL_TimeFormat
89{
90    SDL_TIME_FORMAT_24HR = 0, /**< 24 hour time */
91    SDL_TIME_FORMAT_12HR = 1  /**< 12 hour time */
92} SDL_TimeFormat;
93
94/**
95 * Gets the current preferred date and time format for the system locale.
96 *
97 * This might be a "slow" call that has to query the operating system. It's
98 * best to ask for this once and save the results. However, the preferred
99 * formats can change, usually because the user has changed a system
100 * preference outside of your program.
101 *
102 * \param dateFormat a pointer to the SDL_DateFormat to hold the returned date
103 *                   format, may be NULL.
104 * \param timeFormat a pointer to the SDL_TimeFormat to hold the returned time
105 *                   format, may be NULL.
106 * \returns true on success or false on failure; call SDL_GetError() for more
107 *          information.
108 *
109 * \threadsafety This function is not thread safe.
110 *
111 * \since This function is available since SDL 3.2.0.
112 */
113extern SDL_DECLSPEC bool SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat *dateFormat, SDL_TimeFormat *timeFormat);
114
115/**
116 * Gets the current value of the system realtime clock in nanoseconds since
117 * Jan 1, 1970 in Universal Coordinated Time (UTC).
118 *
119 * \param ticks the SDL_Time to hold the returned tick count.
120 * \returns true on success or false on failure; call SDL_GetError() for more
121 *          information.
122 *
123 * \threadsafety It is safe to call this function from any thread.
124 *
125 * \since This function is available since SDL 3.2.0.
126 */
127extern SDL_DECLSPEC bool SDLCALL SDL_GetCurrentTime(SDL_Time *ticks);
128
129/**
130 * Converts an SDL_Time in nanoseconds since the epoch to a calendar time in
131 * the SDL_DateTime format.
132 *
133 * \param ticks the SDL_Time to be converted.
134 * \param dt the resulting SDL_DateTime.
135 * \param localTime the resulting SDL_DateTime will be expressed in local time
136 *                  if true, otherwise it will be in Universal Coordinated
137 *                  Time (UTC).
138 * \returns true on success or false on failure; call SDL_GetError() for more
139 *          information.
140 *
141 * \threadsafety It is safe to call this function from any thread.
142 *
143 * \since This function is available since SDL 3.2.0.
144 */
145extern SDL_DECLSPEC bool SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime *dt, bool localTime);
146
147/**
148 * Converts a calendar time to an SDL_Time in nanoseconds since the epoch.
149 *
150 * This function ignores the day_of_week member of the SDL_DateTime struct, so
151 * it may remain unset.
152 *
153 * \param dt the source SDL_DateTime.
154 * \param ticks the resulting SDL_Time.
155 * \returns true on success or false on failure; call SDL_GetError() for more
156 *          information.
157 *
158 * \threadsafety It is safe to call this function from any thread.
159 *
160 * \since This function is available since SDL 3.2.0.
161 */
162extern SDL_DECLSPEC bool SDLCALL SDL_DateTimeToTime(const SDL_DateTime *dt, SDL_Time *ticks);
163
164/**
165 * Converts an SDL time into a Windows FILETIME (100-nanosecond intervals
166 * since January 1, 1601).
167 *
168 * This function fills in the two 32-bit values of the FILETIME structure.
169 *
170 * \param ticks the time to convert.
171 * \param dwLowDateTime a pointer filled in with the low portion of the
172 *                      Windows FILETIME value.
173 * \param dwHighDateTime a pointer filled in with the high portion of the
174 *                       Windows FILETIME value.
175 *
176 * \threadsafety It is safe to call this function from any thread.
177 *
178 * \since This function is available since SDL 3.2.0.
179 */
180extern SDL_DECLSPEC void SDLCALL SDL_TimeToWindows(SDL_Time ticks, Uint32 *dwLowDateTime, Uint32 *dwHighDateTime);
181
182/**
183 * Converts a Windows FILETIME (100-nanosecond intervals since January 1,
184 * 1601) to an SDL time.
185 *
186 * This function takes the two 32-bit values of the FILETIME structure as
187 * parameters.
188 *
189 * \param dwLowDateTime the low portion of the Windows FILETIME value.
190 * \param dwHighDateTime the high portion of the Windows FILETIME value.
191 * \returns the converted SDL time.
192 *
193 * \threadsafety It is safe to call this function from any thread.
194 *
195 * \since This function is available since SDL 3.2.0.
196 */
197extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, Uint32 dwHighDateTime);
198
199/**
200 * Get the number of days in a month for a given year.
201 *
202 * \param year the year.
203 * \param month the month [1-12].
204 * \returns the number of days in the requested month or -1 on failure; call
205 *          SDL_GetError() for more information.
206 *
207 * \threadsafety It is safe to call this function from any thread.
208 *
209 * \since This function is available since SDL 3.2.0.
210 */
211extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month);
212
213/**
214 * Get the day of year for a calendar date.
215 *
216 * \param year the year component of the date.
217 * \param month the month component of the date.
218 * \param day the day component of the date.
219 * \returns the day of year [0-365] if the date is valid or -1 on failure;
220 *          call SDL_GetError() for more information.
221 *
222 * \threadsafety It is safe to call this function from any thread.
223 *
224 * \since This function is available since SDL 3.2.0.
225 */
226extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day);
227
228/**
229 * Get the day of week for a calendar date.
230 *
231 * \param year the year component of the date.
232 * \param month the month component of the date.
233 * \param day the day component of the date.
234 * \returns a value between 0 and 6 (0 being Sunday) if the date is valid or
235 *          -1 on failure; call SDL_GetError() for more information.
236 *
237 * \threadsafety It is safe to call this function from any thread.
238 *
239 * \since This function is available since SDL 3.2.0.
240 */
241extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfWeek(int year, int month, int day);
242
243/* Ends C function definitions when using C++ */
244#ifdef __cplusplus
245}
246#endif
247#include <SDL3/SDL_close_code.h>
248
249#endif /* SDL_time_h_ */
250
[FILE END]
(C) 2025 0x4248
(C) 2025 4248 Media and 4248 Systems, All part of 0x4248
See LICENCE files for more information. Not all files are by 0x4248 always check Licencing.