|
1
|
1 /*
|
|
|
2 Simple DirectMedia Layer
|
|
|
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
|
|
|
4
|
|
|
5 This software is provided 'as-is', without any express or implied
|
|
|
6 warranty. In no event will the authors be held liable for any damages
|
|
|
7 arising from the use of this software.
|
|
|
8
|
|
|
9 Permission is granted to anyone to use this software for any purpose,
|
|
|
10 including commercial applications, and to alter it and redistribute it
|
|
|
11 freely, subject to the following restrictions:
|
|
|
12
|
|
|
13 1. 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.
|
|
|
17 2. Altered source versions must be plainly marked as such, and must not be
|
|
|
18 misrepresented as being the original software.
|
|
|
19 3. This notice may not be removed or altered from any source distribution.
|
|
|
20 */
|
|
|
21
|
|
|
22 /**
|
|
|
23 * # CategoryInit
|
|
|
24 *
|
|
|
25 * All SDL programs need to initialize the library before starting to work
|
|
|
26 * with it.
|
|
|
27 *
|
|
|
28 * Almost everything can simply call SDL_Init() near startup, with a handful
|
|
|
29 * of flags to specify subsystems to touch. These are here to make sure SDL
|
|
|
30 * does not even attempt to touch low-level pieces of the operating system
|
|
|
31 * that you don't intend to use. For example, you might be using SDL for video
|
|
|
32 * and input but chose an external library for audio, and in this case you
|
|
|
33 * would just need to leave off the `SDL_INIT_AUDIO` flag to make sure that
|
|
|
34 * external library has complete control.
|
|
|
35 *
|
|
|
36 * Most apps, when terminating, should call SDL_Quit(). This will clean up
|
|
|
37 * (nearly) everything that SDL might have allocated, and crucially, it'll
|
|
|
38 * make sure that the display's resolution is back to what the user expects if
|
|
|
39 * you had previously changed it for your game.
|
|
|
40 *
|
|
|
41 * SDL3 apps are strongly encouraged to call SDL_SetAppMetadata() at startup
|
|
|
42 * to fill in details about the program. This is completely optional, but it
|
|
|
43 * helps in small ways (we can provide an About dialog box for the macOS menu,
|
|
|
44 * we can name the app in the system's audio mixer, etc). Those that want to
|
|
|
45 * provide a _lot_ of information should look at the more-detailed
|
|
|
46 * SDL_SetAppMetadataProperty().
|
|
|
47 */
|
|
|
48
|
|
|
49 #ifndef SDL_init_h_
|
|
|
50 #define SDL_init_h_
|
|
|
51
|
|
|
52 #include <SDL3/SDL_stdinc.h>
|
|
|
53 #include <SDL3/SDL_error.h>
|
|
|
54 #include <SDL3/SDL_events.h>
|
|
|
55
|
|
|
56 #include <SDL3/SDL_begin_code.h>
|
|
|
57 /* Set up for C function definitions, even when using C++ */
|
|
|
58 #ifdef __cplusplus
|
|
|
59 extern "C" {
|
|
|
60 #endif
|
|
|
61
|
|
|
62 /* As of version 0.5, SDL is loaded dynamically into the application */
|
|
|
63
|
|
|
64 /**
|
|
|
65 * Initialization flags for SDL_Init and/or SDL_InitSubSystem
|
|
|
66 *
|
|
|
67 * These are the flags which may be passed to SDL_Init(). You should specify
|
|
|
68 * the subsystems which you will be using in your application.
|
|
|
69 *
|
|
|
70 * \since This datatype is available since SDL 3.2.0.
|
|
|
71 *
|
|
|
72 * \sa SDL_Init
|
|
|
73 * \sa SDL_Quit
|
|
|
74 * \sa SDL_InitSubSystem
|
|
|
75 * \sa SDL_QuitSubSystem
|
|
|
76 * \sa SDL_WasInit
|
|
|
77 */
|
|
|
78 typedef Uint32 SDL_InitFlags;
|
|
|
79
|
|
|
80 #define SDL_INIT_AUDIO 0x00000010u /**< `SDL_INIT_AUDIO` implies `SDL_INIT_EVENTS` */
|
|
|
81 #define SDL_INIT_VIDEO 0x00000020u /**< `SDL_INIT_VIDEO` implies `SDL_INIT_EVENTS`, should be initialized on the main thread */
|
|
|
82 #define SDL_INIT_JOYSTICK 0x00000200u /**< `SDL_INIT_JOYSTICK` implies `SDL_INIT_EVENTS` */
|
|
|
83 #define SDL_INIT_HAPTIC 0x00001000u
|
|
|
84 #define SDL_INIT_GAMEPAD 0x00002000u /**< `SDL_INIT_GAMEPAD` implies `SDL_INIT_JOYSTICK` */
|
|
|
85 #define SDL_INIT_EVENTS 0x00004000u
|
|
|
86 #define SDL_INIT_SENSOR 0x00008000u /**< `SDL_INIT_SENSOR` implies `SDL_INIT_EVENTS` */
|
|
|
87 #define SDL_INIT_CAMERA 0x00010000u /**< `SDL_INIT_CAMERA` implies `SDL_INIT_EVENTS` */
|
|
|
88
|
|
|
89 /**
|
|
|
90 * Return values for optional main callbacks.
|
|
|
91 *
|
|
|
92 * Returning SDL_APP_SUCCESS or SDL_APP_FAILURE from SDL_AppInit,
|
|
|
93 * SDL_AppEvent, or SDL_AppIterate will terminate the program and report
|
|
|
94 * success/failure to the operating system. What that means is
|
|
|
95 * platform-dependent. On Unix, for example, on success, the process error
|
|
|
96 * code will be zero, and on failure it will be 1. This interface doesn't
|
|
|
97 * allow you to return specific exit codes, just whether there was an error
|
|
|
98 * generally or not.
|
|
|
99 *
|
|
|
100 * Returning SDL_APP_CONTINUE from these functions will let the app continue
|
|
|
101 * to run.
|
|
|
102 *
|
|
|
103 * See
|
|
|
104 * [Main callbacks in SDL3](https://wiki.libsdl.org/SDL3/README-main-functions#main-callbacks-in-sdl3)
|
|
|
105 * for complete details.
|
|
|
106 *
|
|
|
107 * \since This enum is available since SDL 3.2.0.
|
|
|
108 */
|
|
|
109 typedef enum SDL_AppResult
|
|
|
110 {
|
|
|
111 SDL_APP_CONTINUE, /**< Value that requests that the app continue from the main callbacks. */
|
|
|
112 SDL_APP_SUCCESS, /**< Value that requests termination with success from the main callbacks. */
|
|
|
113 SDL_APP_FAILURE /**< Value that requests termination with error from the main callbacks. */
|
|
|
114 } SDL_AppResult;
|
|
|
115
|
|
|
116 /**
|
|
|
117 * Function pointer typedef for SDL_AppInit.
|
|
|
118 *
|
|
|
119 * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind
|
|
|
120 * the scenes for apps using the optional main callbacks. Apps that want to
|
|
|
121 * use this should just implement SDL_AppInit directly.
|
|
|
122 *
|
|
|
123 * \param appstate a place where the app can optionally store a pointer for
|
|
|
124 * future use.
|
|
|
125 * \param argc the standard ANSI C main's argc; number of elements in `argv`.
|
|
|
126 * \param argv the standard ANSI C main's argv; array of command line
|
|
|
127 * arguments.
|
|
|
128 * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to
|
|
|
129 * terminate with success, SDL_APP_CONTINUE to continue.
|
|
|
130 *
|
|
|
131 * \since This datatype is available since SDL 3.2.0.
|
|
|
132 */
|
|
|
133 typedef SDL_AppResult (SDLCALL *SDL_AppInit_func)(void **appstate, int argc, char *argv[]);
|
|
|
134
|
|
|
135 /**
|
|
|
136 * Function pointer typedef for SDL_AppIterate.
|
|
|
137 *
|
|
|
138 * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind
|
|
|
139 * the scenes for apps using the optional main callbacks. Apps that want to
|
|
|
140 * use this should just implement SDL_AppIterate directly.
|
|
|
141 *
|
|
|
142 * \param appstate an optional pointer, provided by the app in SDL_AppInit.
|
|
|
143 * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to
|
|
|
144 * terminate with success, SDL_APP_CONTINUE to continue.
|
|
|
145 *
|
|
|
146 * \since This datatype is available since SDL 3.2.0.
|
|
|
147 */
|
|
|
148 typedef SDL_AppResult (SDLCALL *SDL_AppIterate_func)(void *appstate);
|
|
|
149
|
|
|
150 /**
|
|
|
151 * Function pointer typedef for SDL_AppEvent.
|
|
|
152 *
|
|
|
153 * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind
|
|
|
154 * the scenes for apps using the optional main callbacks. Apps that want to
|
|
|
155 * use this should just implement SDL_AppEvent directly.
|
|
|
156 *
|
|
|
157 * \param appstate an optional pointer, provided by the app in SDL_AppInit.
|
|
|
158 * \param event the new event for the app to examine.
|
|
|
159 * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to
|
|
|
160 * terminate with success, SDL_APP_CONTINUE to continue.
|
|
|
161 *
|
|
|
162 * \since This datatype is available since SDL 3.2.0.
|
|
|
163 */
|
|
|
164 typedef SDL_AppResult (SDLCALL *SDL_AppEvent_func)(void *appstate, SDL_Event *event);
|
|
|
165
|
|
|
166 /**
|
|
|
167 * Function pointer typedef for SDL_AppQuit.
|
|
|
168 *
|
|
|
169 * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind
|
|
|
170 * the scenes for apps using the optional main callbacks. Apps that want to
|
|
|
171 * use this should just implement SDL_AppEvent directly.
|
|
|
172 *
|
|
|
173 * \param appstate an optional pointer, provided by the app in SDL_AppInit.
|
|
|
174 * \param result the result code that terminated the app (success or failure).
|
|
|
175 *
|
|
|
176 * \since This datatype is available since SDL 3.2.0.
|
|
|
177 */
|
|
|
178 typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate, SDL_AppResult result);
|
|
|
179
|
|
|
180
|
|
|
181 /**
|
|
|
182 * Initialize the SDL library.
|
|
|
183 *
|
|
|
184 * SDL_Init() simply forwards to calling SDL_InitSubSystem(). Therefore, the
|
|
|
185 * two may be used interchangeably. Though for readability of your code
|
|
|
186 * SDL_InitSubSystem() might be preferred.
|
|
|
187 *
|
|
|
188 * The file I/O (for example: SDL_IOFromFile) and threading (SDL_CreateThread)
|
|
|
189 * subsystems are initialized by default. Message boxes
|
|
|
190 * (SDL_ShowSimpleMessageBox) also attempt to work without initializing the
|
|
|
191 * video subsystem, in hopes of being useful in showing an error dialog when
|
|
|
192 * SDL_Init fails. You must specifically initialize other subsystems if you
|
|
|
193 * use them in your application.
|
|
|
194 *
|
|
|
195 * Logging (such as SDL_Log) works without initialization, too.
|
|
|
196 *
|
|
|
197 * `flags` may be any of the following OR'd together:
|
|
|
198 *
|
|
|
199 * - `SDL_INIT_AUDIO`: audio subsystem; automatically initializes the events
|
|
|
200 * subsystem
|
|
|
201 * - `SDL_INIT_VIDEO`: video subsystem; automatically initializes the events
|
|
|
202 * subsystem, should be initialized on the main thread.
|
|
|
203 * - `SDL_INIT_JOYSTICK`: joystick subsystem; automatically initializes the
|
|
|
204 * events subsystem
|
|
|
205 * - `SDL_INIT_HAPTIC`: haptic (force feedback) subsystem
|
|
|
206 * - `SDL_INIT_GAMEPAD`: gamepad subsystem; automatically initializes the
|
|
|
207 * joystick subsystem
|
|
|
208 * - `SDL_INIT_EVENTS`: events subsystem
|
|
|
209 * - `SDL_INIT_SENSOR`: sensor subsystem; automatically initializes the events
|
|
|
210 * subsystem
|
|
|
211 * - `SDL_INIT_CAMERA`: camera subsystem; automatically initializes the events
|
|
|
212 * subsystem
|
|
|
213 *
|
|
|
214 * Subsystem initialization is ref-counted, you must call SDL_QuitSubSystem()
|
|
|
215 * for each SDL_InitSubSystem() to correctly shutdown a subsystem manually (or
|
|
|
216 * call SDL_Quit() to force shutdown). If a subsystem is already loaded then
|
|
|
217 * this call will increase the ref-count and return.
|
|
|
218 *
|
|
|
219 * Consider reporting some basic metadata about your application before
|
|
|
220 * calling SDL_Init, using either SDL_SetAppMetadata() or
|
|
|
221 * SDL_SetAppMetadataProperty().
|
|
|
222 *
|
|
|
223 * \param flags subsystem initialization flags.
|
|
|
224 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
225 * information.
|
|
|
226 *
|
|
|
227 * \since This function is available since SDL 3.2.0.
|
|
|
228 *
|
|
|
229 * \sa SDL_SetAppMetadata
|
|
|
230 * \sa SDL_SetAppMetadataProperty
|
|
|
231 * \sa SDL_InitSubSystem
|
|
|
232 * \sa SDL_Quit
|
|
|
233 * \sa SDL_SetMainReady
|
|
|
234 * \sa SDL_WasInit
|
|
|
235 */
|
|
|
236 extern SDL_DECLSPEC bool SDLCALL SDL_Init(SDL_InitFlags flags);
|
|
|
237
|
|
|
238 /**
|
|
|
239 * Compatibility function to initialize the SDL library.
|
|
|
240 *
|
|
|
241 * This function and SDL_Init() are interchangeable.
|
|
|
242 *
|
|
|
243 * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
|
|
|
244 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
245 * information.
|
|
|
246 *
|
|
|
247 * \since This function is available since SDL 3.2.0.
|
|
|
248 *
|
|
|
249 * \sa SDL_Init
|
|
|
250 * \sa SDL_Quit
|
|
|
251 * \sa SDL_QuitSubSystem
|
|
|
252 */
|
|
|
253 extern SDL_DECLSPEC bool SDLCALL SDL_InitSubSystem(SDL_InitFlags flags);
|
|
|
254
|
|
|
255 /**
|
|
|
256 * Shut down specific SDL subsystems.
|
|
|
257 *
|
|
|
258 * You still need to call SDL_Quit() even if you close all open subsystems
|
|
|
259 * with SDL_QuitSubSystem().
|
|
|
260 *
|
|
|
261 * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
|
|
|
262 *
|
|
|
263 * \since This function is available since SDL 3.2.0.
|
|
|
264 *
|
|
|
265 * \sa SDL_InitSubSystem
|
|
|
266 * \sa SDL_Quit
|
|
|
267 */
|
|
|
268 extern SDL_DECLSPEC void SDLCALL SDL_QuitSubSystem(SDL_InitFlags flags);
|
|
|
269
|
|
|
270 /**
|
|
|
271 * Get a mask of the specified subsystems which are currently initialized.
|
|
|
272 *
|
|
|
273 * \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
|
|
|
274 * \returns a mask of all initialized subsystems if `flags` is 0, otherwise it
|
|
|
275 * returns the initialization status of the specified subsystems.
|
|
|
276 *
|
|
|
277 * \since This function is available since SDL 3.2.0.
|
|
|
278 *
|
|
|
279 * \sa SDL_Init
|
|
|
280 * \sa SDL_InitSubSystem
|
|
|
281 */
|
|
|
282 extern SDL_DECLSPEC SDL_InitFlags SDLCALL SDL_WasInit(SDL_InitFlags flags);
|
|
|
283
|
|
|
284 /**
|
|
|
285 * Clean up all initialized subsystems.
|
|
|
286 *
|
|
|
287 * You should call this function even if you have already shutdown each
|
|
|
288 * initialized subsystem with SDL_QuitSubSystem(). It is safe to call this
|
|
|
289 * function even in the case of errors in initialization.
|
|
|
290 *
|
|
|
291 * You can use this function with atexit() to ensure that it is run when your
|
|
|
292 * application is shutdown, but it is not wise to do this from a library or
|
|
|
293 * other dynamically loaded code.
|
|
|
294 *
|
|
|
295 * \since This function is available since SDL 3.2.0.
|
|
|
296 *
|
|
|
297 * \sa SDL_Init
|
|
|
298 * \sa SDL_QuitSubSystem
|
|
|
299 */
|
|
|
300 extern SDL_DECLSPEC void SDLCALL SDL_Quit(void);
|
|
|
301
|
|
|
302 /**
|
|
|
303 * Return whether this is the main thread.
|
|
|
304 *
|
|
|
305 * On Apple platforms, the main thread is the thread that runs your program's
|
|
|
306 * main() entry point. On other platforms, the main thread is the one that
|
|
|
307 * calls SDL_Init(SDL_INIT_VIDEO), which should usually be the one that runs
|
|
|
308 * your program's main() entry point. If you are using the main callbacks,
|
|
|
309 * SDL_AppInit(), SDL_AppIterate(), and SDL_AppQuit() are all called on the
|
|
|
310 * main thread.
|
|
|
311 *
|
|
|
312 * \returns true if this thread is the main thread, or false otherwise.
|
|
|
313 *
|
|
|
314 * \threadsafety It is safe to call this function from any thread.
|
|
|
315 *
|
|
|
316 * \since This function is available since SDL 3.2.0.
|
|
|
317 *
|
|
|
318 * \sa SDL_RunOnMainThread
|
|
|
319 */
|
|
|
320 extern SDL_DECLSPEC bool SDLCALL SDL_IsMainThread(void);
|
|
|
321
|
|
|
322 /**
|
|
|
323 * Callback run on the main thread.
|
|
|
324 *
|
|
|
325 * \param userdata an app-controlled pointer that is passed to the callback.
|
|
|
326 *
|
|
|
327 * \since This datatype is available since SDL 3.2.0.
|
|
|
328 *
|
|
|
329 * \sa SDL_RunOnMainThread
|
|
|
330 */
|
|
|
331 typedef void (SDLCALL *SDL_MainThreadCallback)(void *userdata);
|
|
|
332
|
|
|
333 /**
|
|
|
334 * Call a function on the main thread during event processing.
|
|
|
335 *
|
|
|
336 * If this is called on the main thread, the callback is executed immediately.
|
|
|
337 * If this is called on another thread, this callback is queued for execution
|
|
|
338 * on the main thread during event processing.
|
|
|
339 *
|
|
|
340 * Be careful of deadlocks when using this functionality. You should not have
|
|
|
341 * the main thread wait for the current thread while this function is being
|
|
|
342 * called with `wait_complete` true.
|
|
|
343 *
|
|
|
344 * \param callback the callback to call on the main thread.
|
|
|
345 * \param userdata a pointer that is passed to `callback`.
|
|
|
346 * \param wait_complete true to wait for the callback to complete, false to
|
|
|
347 * return immediately.
|
|
|
348 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
349 * information.
|
|
|
350 *
|
|
|
351 * \threadsafety It is safe to call this function from any thread.
|
|
|
352 *
|
|
|
353 * \since This function is available since SDL 3.2.0.
|
|
|
354 *
|
|
|
355 * \sa SDL_IsMainThread
|
|
|
356 */
|
|
|
357 extern SDL_DECLSPEC bool SDLCALL SDL_RunOnMainThread(SDL_MainThreadCallback callback, void *userdata, bool wait_complete);
|
|
|
358
|
|
|
359 /**
|
|
|
360 * Specify basic metadata about your app.
|
|
|
361 *
|
|
|
362 * You can optionally provide metadata about your app to SDL. This is not
|
|
|
363 * required, but strongly encouraged.
|
|
|
364 *
|
|
|
365 * There are several locations where SDL can make use of metadata (an "About"
|
|
|
366 * box in the macOS menu bar, the name of the app can be shown on some audio
|
|
|
367 * mixers, etc). Any piece of metadata can be left as NULL, if a specific
|
|
|
368 * detail doesn't make sense for the app.
|
|
|
369 *
|
|
|
370 * This function should be called as early as possible, before SDL_Init.
|
|
|
371 * Multiple calls to this function are allowed, but various state might not
|
|
|
372 * change once it has been set up with a previous call to this function.
|
|
|
373 *
|
|
|
374 * Passing a NULL removes any previous metadata.
|
|
|
375 *
|
|
|
376 * This is a simplified interface for the most important information. You can
|
|
|
377 * supply significantly more detailed metadata with
|
|
|
378 * SDL_SetAppMetadataProperty().
|
|
|
379 *
|
|
|
380 * \param appname The name of the application ("My Game 2: Bad Guy's
|
|
|
381 * Revenge!").
|
|
|
382 * \param appversion The version of the application ("1.0.0beta5" or a git
|
|
|
383 * hash, or whatever makes sense).
|
|
|
384 * \param appidentifier A unique string in reverse-domain format that
|
|
|
385 * identifies this app ("com.example.mygame2").
|
|
|
386 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
387 * information.
|
|
|
388 *
|
|
|
389 * \threadsafety It is safe to call this function from any thread.
|
|
|
390 *
|
|
|
391 * \since This function is available since SDL 3.2.0.
|
|
|
392 *
|
|
|
393 * \sa SDL_SetAppMetadataProperty
|
|
|
394 */
|
|
|
395 extern SDL_DECLSPEC bool SDLCALL SDL_SetAppMetadata(const char *appname, const char *appversion, const char *appidentifier);
|
|
|
396
|
|
|
397 /**
|
|
|
398 * Specify metadata about your app through a set of properties.
|
|
|
399 *
|
|
|
400 * You can optionally provide metadata about your app to SDL. This is not
|
|
|
401 * required, but strongly encouraged.
|
|
|
402 *
|
|
|
403 * There are several locations where SDL can make use of metadata (an "About"
|
|
|
404 * box in the macOS menu bar, the name of the app can be shown on some audio
|
|
|
405 * mixers, etc). Any piece of metadata can be left out, if a specific detail
|
|
|
406 * doesn't make sense for the app.
|
|
|
407 *
|
|
|
408 * This function should be called as early as possible, before SDL_Init.
|
|
|
409 * Multiple calls to this function are allowed, but various state might not
|
|
|
410 * change once it has been set up with a previous call to this function.
|
|
|
411 *
|
|
|
412 * Once set, this metadata can be read using SDL_GetAppMetadataProperty().
|
|
|
413 *
|
|
|
414 * These are the supported properties:
|
|
|
415 *
|
|
|
416 * - `SDL_PROP_APP_METADATA_NAME_STRING`: The human-readable name of the
|
|
|
417 * application, like "My Game 2: Bad Guy's Revenge!". This will show up
|
|
|
418 * anywhere the OS shows the name of the application separately from window
|
|
|
419 * titles, such as volume control applets, etc. This defaults to "SDL
|
|
|
420 * Application".
|
|
|
421 * - `SDL_PROP_APP_METADATA_VERSION_STRING`: The version of the app that is
|
|
|
422 * running; there are no rules on format, so "1.0.3beta2" and "April 22nd,
|
|
|
423 * 2024" and a git hash are all valid options. This has no default.
|
|
|
424 * - `SDL_PROP_APP_METADATA_IDENTIFIER_STRING`: A unique string that
|
|
|
425 * identifies this app. This must be in reverse-domain format, like
|
|
|
426 * "com.example.mygame2". This string is used by desktop compositors to
|
|
|
427 * identify and group windows together, as well as match applications with
|
|
|
428 * associated desktop settings and icons. If you plan to package your
|
|
|
429 * application in a container such as Flatpak, the app ID should match the
|
|
|
430 * name of your Flatpak container as well. This has no default.
|
|
|
431 * - `SDL_PROP_APP_METADATA_CREATOR_STRING`: The human-readable name of the
|
|
|
432 * creator/developer/maker of this app, like "MojoWorkshop, LLC"
|
|
|
433 * - `SDL_PROP_APP_METADATA_COPYRIGHT_STRING`: The human-readable copyright
|
|
|
434 * notice, like "Copyright (c) 2024 MojoWorkshop, LLC" or whatnot. Keep this
|
|
|
435 * to one line, don't paste a copy of a whole software license in here. This
|
|
|
436 * has no default.
|
|
|
437 * - `SDL_PROP_APP_METADATA_URL_STRING`: A URL to the app on the web. Maybe a
|
|
|
438 * product page, or a storefront, or even a GitHub repository, for user's
|
|
|
439 * further information This has no default.
|
|
|
440 * - `SDL_PROP_APP_METADATA_TYPE_STRING`: The type of application this is.
|
|
|
441 * Currently this string can be "game" for a video game, "mediaplayer" for a
|
|
|
442 * media player, or generically "application" if nothing else applies.
|
|
|
443 * Future versions of SDL might add new types. This defaults to
|
|
|
444 * "application".
|
|
|
445 *
|
|
|
446 * \param name the name of the metadata property to set.
|
|
|
447 * \param value the value of the property, or NULL to remove that property.
|
|
|
448 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
449 * information.
|
|
|
450 *
|
|
|
451 * \threadsafety It is safe to call this function from any thread.
|
|
|
452 *
|
|
|
453 * \since This function is available since SDL 3.2.0.
|
|
|
454 *
|
|
|
455 * \sa SDL_GetAppMetadataProperty
|
|
|
456 * \sa SDL_SetAppMetadata
|
|
|
457 */
|
|
|
458 extern SDL_DECLSPEC bool SDLCALL SDL_SetAppMetadataProperty(const char *name, const char *value);
|
|
|
459
|
|
|
460 #define SDL_PROP_APP_METADATA_NAME_STRING "SDL.app.metadata.name"
|
|
|
461 #define SDL_PROP_APP_METADATA_VERSION_STRING "SDL.app.metadata.version"
|
|
|
462 #define SDL_PROP_APP_METADATA_IDENTIFIER_STRING "SDL.app.metadata.identifier"
|
|
|
463 #define SDL_PROP_APP_METADATA_CREATOR_STRING "SDL.app.metadata.creator"
|
|
|
464 #define SDL_PROP_APP_METADATA_COPYRIGHT_STRING "SDL.app.metadata.copyright"
|
|
|
465 #define SDL_PROP_APP_METADATA_URL_STRING "SDL.app.metadata.url"
|
|
|
466 #define SDL_PROP_APP_METADATA_TYPE_STRING "SDL.app.metadata.type"
|
|
|
467
|
|
|
468 /**
|
|
|
469 * Get metadata about your app.
|
|
|
470 *
|
|
|
471 * This returns metadata previously set using SDL_SetAppMetadata() or
|
|
|
472 * SDL_SetAppMetadataProperty(). See SDL_SetAppMetadataProperty() for the list
|
|
|
473 * of available properties and their meanings.
|
|
|
474 *
|
|
|
475 * \param name the name of the metadata property to get.
|
|
|
476 * \returns the current value of the metadata property, or the default if it
|
|
|
477 * is not set, NULL for properties with no default.
|
|
|
478 *
|
|
|
479 * \threadsafety It is safe to call this function from any thread, although
|
|
|
480 * the string returned is not protected and could potentially be
|
|
|
481 * freed if you call SDL_SetAppMetadataProperty() to set that
|
|
|
482 * property from another thread.
|
|
|
483 *
|
|
|
484 * \since This function is available since SDL 3.2.0.
|
|
|
485 *
|
|
|
486 * \sa SDL_SetAppMetadata
|
|
|
487 * \sa SDL_SetAppMetadataProperty
|
|
|
488 */
|
|
|
489 extern SDL_DECLSPEC const char * SDLCALL SDL_GetAppMetadataProperty(const char *name);
|
|
|
490
|
|
|
491 /* Ends C function definitions when using C++ */
|
|
|
492 #ifdef __cplusplus
|
|
|
493 }
|
|
|
494 #endif
|
|
|
495 #include <SDL3/SDL_close_code.h>
|
|
|
496
|
|
|
497 #endif /* SDL_init_h_ */
|
