|
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 * # CategoryMain
|
|
|
24 *
|
|
|
25 * Redefine main() if necessary so that it is called by SDL.
|
|
|
26 *
|
|
|
27 * In order to make this consistent on all platforms, the application's main()
|
|
|
28 * should look like this:
|
|
|
29 *
|
|
|
30 * ```c
|
|
|
31 * #include <SDL3/SDL.h>
|
|
|
32 * #include <SDL3/SDL_main.h>
|
|
|
33 *
|
|
|
34 * int main(int argc, char *argv[])
|
|
|
35 * {
|
|
|
36 * }
|
|
|
37 * ```
|
|
|
38 *
|
|
|
39 * SDL will take care of platform specific details on how it gets called.
|
|
|
40 *
|
|
|
41 * This is also where an app can be configured to use the main callbacks, via
|
|
|
42 * the SDL_MAIN_USE_CALLBACKS macro.
|
|
|
43 *
|
|
|
44 * SDL_main.h is a "single-header library," which is to say that including
|
|
|
45 * this header inserts code into your program, and you should only include it
|
|
|
46 * once in most cases. SDL.h does not include this header automatically.
|
|
|
47 *
|
|
|
48 * For more information, see:
|
|
|
49 *
|
|
|
50 * https://wiki.libsdl.org/SDL3/README-main-functions
|
|
|
51 */
|
|
|
52
|
|
|
53 #ifndef SDL_main_h_
|
|
|
54 #define SDL_main_h_
|
|
|
55
|
|
|
56 #include <SDL3/SDL_platform_defines.h>
|
|
|
57 #include <SDL3/SDL_stdinc.h>
|
|
|
58 #include <SDL3/SDL_error.h>
|
|
|
59 #include <SDL3/SDL_events.h>
|
|
|
60
|
|
|
61 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
|
|
|
62
|
|
|
63 /**
|
|
|
64 * Inform SDL that the app is providing an entry point instead of SDL.
|
|
|
65 *
|
|
|
66 * SDL does not define this macro, but will check if it is defined when
|
|
|
67 * including `SDL_main.h`. If defined, SDL will expect the app to provide the
|
|
|
68 * proper entry point for the platform, and all the other magic details
|
|
|
69 * needed, like manually calling SDL_SetMainReady.
|
|
|
70 *
|
|
|
71 * Please see [README-main-functions](README-main-functions), (or
|
|
|
72 * docs/README-main-functions.md in the source tree) for a more detailed
|
|
|
73 * explanation.
|
|
|
74 *
|
|
|
75 * \since This macro is used by the headers since SDL 3.2.0.
|
|
|
76 */
|
|
|
77 #define SDL_MAIN_HANDLED 1
|
|
|
78
|
|
|
79 /**
|
|
|
80 * Inform SDL to use the main callbacks instead of main.
|
|
|
81 *
|
|
|
82 * SDL does not define this macro, but will check if it is defined when
|
|
|
83 * including `SDL_main.h`. If defined, SDL will expect the app to provide
|
|
|
84 * several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and
|
|
|
85 * SDL_AppQuit. The app should not provide a `main` function in this case, and
|
|
|
86 * doing so will likely cause the build to fail.
|
|
|
87 *
|
|
|
88 * Please see [README-main-functions](README-main-functions), (or
|
|
|
89 * docs/README-main-functions.md in the source tree) for a more detailed
|
|
|
90 * explanation.
|
|
|
91 *
|
|
|
92 * \since This macro is used by the headers since SDL 3.2.0.
|
|
|
93 *
|
|
|
94 * \sa SDL_AppInit
|
|
|
95 * \sa SDL_AppEvent
|
|
|
96 * \sa SDL_AppIterate
|
|
|
97 * \sa SDL_AppQuit
|
|
|
98 */
|
|
|
99 #define SDL_MAIN_USE_CALLBACKS 1
|
|
|
100
|
|
|
101 /**
|
|
|
102 * Defined if the target platform offers a special mainline through SDL.
|
|
|
103 *
|
|
|
104 * This won't be defined otherwise. If defined, SDL's headers will redefine
|
|
|
105 * `main` to `SDL_main`.
|
|
|
106 *
|
|
|
107 * This macro is defined by `SDL_main.h`, which is not automatically included
|
|
|
108 * by `SDL.h`.
|
|
|
109 *
|
|
|
110 * Even if available, an app can define SDL_MAIN_HANDLED and provide their
|
|
|
111 * own, if they know what they're doing.
|
|
|
112 *
|
|
|
113 * This macro is used internally by SDL, and apps probably shouldn't rely on
|
|
|
114 * it.
|
|
|
115 *
|
|
|
116 * \since This macro is available since SDL 3.2.0.
|
|
|
117 */
|
|
|
118 #define SDL_MAIN_AVAILABLE
|
|
|
119
|
|
|
120 /**
|
|
|
121 * Defined if the target platform _requires_ a special mainline through SDL.
|
|
|
122 *
|
|
|
123 * This won't be defined otherwise. If defined, SDL's headers will redefine
|
|
|
124 * `main` to `SDL_main`.
|
|
|
125 *
|
|
|
126 * This macro is defined by `SDL_main.h`, which is not automatically included
|
|
|
127 * by `SDL.h`.
|
|
|
128 *
|
|
|
129 * Even if required, an app can define SDL_MAIN_HANDLED and provide their own,
|
|
|
130 * if they know what they're doing.
|
|
|
131 *
|
|
|
132 * This macro is used internally by SDL, and apps probably shouldn't rely on
|
|
|
133 * it.
|
|
|
134 *
|
|
|
135 * \since This macro is available since SDL 3.2.0.
|
|
|
136 */
|
|
|
137 #define SDL_MAIN_NEEDED
|
|
|
138
|
|
|
139 #endif
|
|
|
140
|
|
|
141 #if defined(__has_include)
|
|
|
142 #if __has_include("SDL_main_private.h") && __has_include("SDL_main_impl_private.h")
|
|
|
143 #define SDL_PLATFORM_PRIVATE_MAIN
|
|
|
144 #endif
|
|
|
145 #endif
|
|
|
146
|
|
|
147 #ifndef SDL_MAIN_HANDLED
|
|
|
148 #if defined(SDL_PLATFORM_PRIVATE_MAIN)
|
|
|
149 /* Private platforms may have their own ideas about entry points. */
|
|
|
150 #include "SDL_main_private.h"
|
|
|
151
|
|
|
152 #elif defined(SDL_PLATFORM_WIN32)
|
|
|
153 /* On Windows SDL provides WinMain(), which parses the command line and passes
|
|
|
154 the arguments to your main function.
|
|
|
155
|
|
|
156 If you provide your own WinMain(), you may define SDL_MAIN_HANDLED
|
|
|
157 */
|
|
|
158 #define SDL_MAIN_AVAILABLE
|
|
|
159
|
|
|
160 #elif defined(SDL_PLATFORM_GDK)
|
|
|
161 /* On GDK, SDL provides a main function that initializes the game runtime.
|
|
|
162
|
|
|
163 If you prefer to write your own WinMain-function instead of having SDL
|
|
|
164 provide one that calls your main() function,
|
|
|
165 #define SDL_MAIN_HANDLED before #include'ing SDL_main.h
|
|
|
166 and call the SDL_RunApp function from your entry point.
|
|
|
167 */
|
|
|
168 #define SDL_MAIN_NEEDED
|
|
|
169
|
|
|
170 #elif defined(SDL_PLATFORM_IOS) || defined(SDL_PLATFORM_TVOS)
|
|
|
171 /* On iOS and tvOS SDL provides a main function that creates an application delegate and starts the application run loop.
|
|
|
172
|
|
|
173 To use it, just #include <SDL3/SDL_main.h> in the source file that contains your main() function.
|
|
|
174
|
|
|
175 See src/video/uikit/SDL_uikitappdelegate.m for more details.
|
|
|
176 */
|
|
|
177 #define SDL_MAIN_NEEDED
|
|
|
178
|
|
|
179 #elif defined(SDL_PLATFORM_ANDROID)
|
|
|
180 /* On Android SDL provides a Java class in SDLActivity.java that is the
|
|
|
181 main activity entry point.
|
|
|
182
|
|
|
183 See docs/README-android.md for more details on extending that class.
|
|
|
184 */
|
|
|
185 #define SDL_MAIN_NEEDED
|
|
|
186
|
|
|
187 /* As this is launched from Java, the real entry point (main() function)
|
|
|
188 is outside of the the binary built from this code.
|
|
|
189 This define makes sure that, unlike on other platforms, SDL_main.h
|
|
|
190 and SDL_main_impl.h export an `SDL_main()` function (to be called
|
|
|
191 from Java), but don't implement a native `int main(int argc, char* argv[])`
|
|
|
192 or similar.
|
|
|
193 */
|
|
|
194 #define SDL_MAIN_EXPORTED
|
|
|
195
|
|
|
196 #elif defined(SDL_PLATFORM_EMSCRIPTEN)
|
|
|
197 /* On Emscripten, SDL provides a main function that converts URL
|
|
|
198 parameters that start with "SDL_" to environment variables, so
|
|
|
199 they can be used as SDL hints, etc.
|
|
|
200
|
|
|
201 This is 100% optional, so if you don't want this to happen, you may
|
|
|
202 define SDL_MAIN_HANDLED
|
|
|
203 */
|
|
|
204 #define SDL_MAIN_AVAILABLE
|
|
|
205
|
|
|
206 #elif defined(SDL_PLATFORM_PSP)
|
|
|
207 /* On PSP SDL provides a main function that sets the module info,
|
|
|
208 activates the GPU and starts the thread required to be able to exit
|
|
|
209 the software.
|
|
|
210
|
|
|
211 If you provide this yourself, you may define SDL_MAIN_HANDLED
|
|
|
212 */
|
|
|
213 #define SDL_MAIN_AVAILABLE
|
|
|
214
|
|
|
215 #elif defined(SDL_PLATFORM_PS2)
|
|
|
216 #define SDL_MAIN_AVAILABLE
|
|
|
217
|
|
|
218 #define SDL_PS2_SKIP_IOP_RESET() \
|
|
|
219 void reset_IOP(); \
|
|
|
220 void reset_IOP() {}
|
|
|
221
|
|
|
222 #elif defined(SDL_PLATFORM_3DS)
|
|
|
223 /*
|
|
|
224 On N3DS, SDL provides a main function that sets up the screens
|
|
|
225 and storage.
|
|
|
226
|
|
|
227 If you provide this yourself, you may define SDL_MAIN_HANDLED
|
|
|
228 */
|
|
|
229 #define SDL_MAIN_AVAILABLE
|
|
|
230
|
|
|
231 #endif
|
|
|
232 #endif /* SDL_MAIN_HANDLED */
|
|
|
233
|
|
|
234
|
|
|
235 #ifdef SDL_WIKI_DOCUMENTATION_SECTION
|
|
|
236
|
|
|
237 /**
|
|
|
238 * A macro to tag a main entry point function as exported.
|
|
|
239 *
|
|
|
240 * Most platforms don't need this, and the macro will be defined to nothing.
|
|
|
241 * Some, like Android, keep the entry points in a shared library and need to
|
|
|
242 * explicitly export the symbols.
|
|
|
243 *
|
|
|
244 * External code rarely needs this, and if it needs something, it's almost
|
|
|
245 * always SDL_DECLSPEC instead.
|
|
|
246 *
|
|
|
247 * \since This macro is available since SDL 3.2.0.
|
|
|
248 *
|
|
|
249 * \sa SDL_DECLSPEC
|
|
|
250 */
|
|
|
251 #define SDLMAIN_DECLSPEC
|
|
|
252
|
|
|
253 #elif defined(SDL_MAIN_EXPORTED)
|
|
|
254 /* We need to export SDL_main so it can be launched from external code,
|
|
|
255 like SDLActivity.java on Android */
|
|
|
256 #define SDLMAIN_DECLSPEC SDL_DECLSPEC
|
|
|
257 #else
|
|
|
258 /* usually this is empty */
|
|
|
259 #define SDLMAIN_DECLSPEC
|
|
|
260 #endif /* SDL_MAIN_EXPORTED */
|
|
|
261
|
|
|
262 #if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) || defined(SDL_MAIN_USE_CALLBACKS)
|
|
|
263 #define main SDL_main
|
|
|
264 #endif
|
|
|
265
|
|
|
266 #include <SDL3/SDL_init.h>
|
|
|
267 #include <SDL3/SDL_begin_code.h>
|
|
|
268 #ifdef __cplusplus
|
|
|
269 extern "C" {
|
|
|
270 #endif
|
|
|
271
|
|
|
272 /*
|
|
|
273 * You can (optionally!) define SDL_MAIN_USE_CALLBACKS before including
|
|
|
274 * SDL_main.h, and then your application will _not_ have a standard
|
|
|
275 * "main" entry point. Instead, it will operate as a collection of
|
|
|
276 * functions that are called as necessary by the system. On some
|
|
|
277 * platforms, this is just a layer where SDL drives your program
|
|
|
278 * instead of your program driving SDL, on other platforms this might
|
|
|
279 * hook into the OS to manage the lifecycle. Programs on most platforms
|
|
|
280 * can use whichever approach they prefer, but the decision boils down
|
|
|
281 * to:
|
|
|
282 *
|
|
|
283 * - Using a standard "main" function: this works like it always has for
|
|
|
284 * the past 50+ years in C programming, and your app is in control.
|
|
|
285 * - Using the callback functions: this might clean up some code,
|
|
|
286 * avoid some #ifdef blocks in your program for some platforms, be more
|
|
|
287 * resource-friendly to the system, and possibly be the primary way to
|
|
|
288 * access some future platforms (but none require this at the moment).
|
|
|
289 *
|
|
|
290 * This is up to the app; both approaches are considered valid and supported
|
|
|
291 * ways to write SDL apps.
|
|
|
292 *
|
|
|
293 * If using the callbacks, don't define a "main" function. Instead, implement
|
|
|
294 * the functions listed below in your program.
|
|
|
295 */
|
|
|
296 #ifdef SDL_MAIN_USE_CALLBACKS
|
|
|
297
|
|
|
298 /**
|
|
|
299 * App-implemented initial entry point for SDL_MAIN_USE_CALLBACKS apps.
|
|
|
300 *
|
|
|
301 * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a
|
|
|
302 * standard "main" function, you should not supply this.
|
|
|
303 *
|
|
|
304 * This function is called by SDL once, at startup. The function should
|
|
|
305 * initialize whatever is necessary, possibly create windows and open audio
|
|
|
306 * devices, etc. The `argc` and `argv` parameters work like they would with a
|
|
|
307 * standard "main" function.
|
|
|
308 *
|
|
|
309 * This function should not go into an infinite mainloop; it should do any
|
|
|
310 * one-time setup it requires and then return.
|
|
|
311 *
|
|
|
312 * The app may optionally assign a pointer to `*appstate`. This pointer will
|
|
|
313 * be provided on every future call to the other entry points, to allow
|
|
|
314 * application state to be preserved between functions without the app needing
|
|
|
315 * to use a global variable. If this isn't set, the pointer will be NULL in
|
|
|
316 * future entry points.
|
|
|
317 *
|
|
|
318 * If this function returns SDL_APP_CONTINUE, the app will proceed to normal
|
|
|
319 * operation, and will begin receiving repeated calls to SDL_AppIterate and
|
|
|
320 * SDL_AppEvent for the life of the program. If this function returns
|
|
|
321 * SDL_APP_FAILURE, SDL will call SDL_AppQuit and terminate the process with
|
|
|
322 * an exit code that reports an error to the platform. If it returns
|
|
|
323 * SDL_APP_SUCCESS, SDL calls SDL_AppQuit and terminates with an exit code
|
|
|
324 * that reports success to the platform.
|
|
|
325 *
|
|
|
326 * This function is called by SDL on the main thread.
|
|
|
327 *
|
|
|
328 * \param appstate a place where the app can optionally store a pointer for
|
|
|
329 * future use.
|
|
|
330 * \param argc the standard ANSI C main's argc; number of elements in `argv`.
|
|
|
331 * \param argv the standard ANSI C main's argv; array of command line
|
|
|
332 * arguments.
|
|
|
333 * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to
|
|
|
334 * terminate with success, SDL_APP_CONTINUE to continue.
|
|
|
335 *
|
|
|
336 * \since This function is available since SDL 3.2.0.
|
|
|
337 *
|
|
|
338 * \sa SDL_AppIterate
|
|
|
339 * \sa SDL_AppEvent
|
|
|
340 * \sa SDL_AppQuit
|
|
|
341 */
|
|
|
342 extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppInit(void **appstate, int argc, char *argv[]);
|
|
|
343
|
|
|
344 /**
|
|
|
345 * App-implemented iteration entry point for SDL_MAIN_USE_CALLBACKS apps.
|
|
|
346 *
|
|
|
347 * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a
|
|
|
348 * standard "main" function, you should not supply this.
|
|
|
349 *
|
|
|
350 * This function is called repeatedly by SDL after SDL_AppInit returns
|
|
|
351 * SDL_APP_CONTINUE. The function should operate as a single iteration the
|
|
|
352 * program's primary loop; it should update whatever state it needs and draw a
|
|
|
353 * new frame of video, usually.
|
|
|
354 *
|
|
|
355 * On some platforms, this function will be called at the refresh rate of the
|
|
|
356 * display (which might change during the life of your app!). There are no
|
|
|
357 * promises made about what frequency this function might run at. You should
|
|
|
358 * use SDL's timer functions if you need to see how much time has passed since
|
|
|
359 * the last iteration.
|
|
|
360 *
|
|
|
361 * There is no need to process the SDL event queue during this function; SDL
|
|
|
362 * will send events as they arrive in SDL_AppEvent, and in most cases the
|
|
|
363 * event queue will be empty when this function runs anyhow.
|
|
|
364 *
|
|
|
365 * This function should not go into an infinite mainloop; it should do one
|
|
|
366 * iteration of whatever the program does and return.
|
|
|
367 *
|
|
|
368 * The `appstate` parameter is an optional pointer provided by the app during
|
|
|
369 * SDL_AppInit(). If the app never provided a pointer, this will be NULL.
|
|
|
370 *
|
|
|
371 * If this function returns SDL_APP_CONTINUE, the app will continue normal
|
|
|
372 * operation, receiving repeated calls to SDL_AppIterate and SDL_AppEvent for
|
|
|
373 * the life of the program. If this function returns SDL_APP_FAILURE, SDL will
|
|
|
374 * call SDL_AppQuit and terminate the process with an exit code that reports
|
|
|
375 * an error to the platform. If it returns SDL_APP_SUCCESS, SDL calls
|
|
|
376 * SDL_AppQuit and terminates with an exit code that reports success to the
|
|
|
377 * platform.
|
|
|
378 *
|
|
|
379 * This function is called by SDL on the main thread.
|
|
|
380 *
|
|
|
381 * \param appstate an optional pointer, provided by the app in SDL_AppInit.
|
|
|
382 * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to
|
|
|
383 * terminate with success, SDL_APP_CONTINUE to continue.
|
|
|
384 *
|
|
|
385 * \threadsafety This function may get called concurrently with SDL_AppEvent()
|
|
|
386 * for events not pushed on the main thread.
|
|
|
387 *
|
|
|
388 * \since This function is available since SDL 3.2.0.
|
|
|
389 *
|
|
|
390 * \sa SDL_AppInit
|
|
|
391 * \sa SDL_AppEvent
|
|
|
392 */
|
|
|
393 extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppIterate(void *appstate);
|
|
|
394
|
|
|
395 /**
|
|
|
396 * App-implemented event entry point for SDL_MAIN_USE_CALLBACKS apps.
|
|
|
397 *
|
|
|
398 * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a
|
|
|
399 * standard "main" function, you should not supply this.
|
|
|
400 *
|
|
|
401 * This function is called as needed by SDL after SDL_AppInit returns
|
|
|
402 * SDL_APP_CONTINUE. It is called once for each new event.
|
|
|
403 *
|
|
|
404 * There is (currently) no guarantee about what thread this will be called
|
|
|
405 * from; whatever thread pushes an event onto SDL's queue will trigger this
|
|
|
406 * function. SDL is responsible for pumping the event queue between each call
|
|
|
407 * to SDL_AppIterate, so in normal operation one should only get events in a
|
|
|
408 * serial fashion, but be careful if you have a thread that explicitly calls
|
|
|
409 * SDL_PushEvent. SDL itself will push events to the queue on the main thread.
|
|
|
410 *
|
|
|
411 * Events sent to this function are not owned by the app; if you need to save
|
|
|
412 * the data, you should copy it.
|
|
|
413 *
|
|
|
414 * This function should not go into an infinite mainloop; it should handle the
|
|
|
415 * provided event appropriately and return.
|
|
|
416 *
|
|
|
417 * The `appstate` parameter is an optional pointer provided by the app during
|
|
|
418 * SDL_AppInit(). If the app never provided a pointer, this will be NULL.
|
|
|
419 *
|
|
|
420 * If this function returns SDL_APP_CONTINUE, the app will continue normal
|
|
|
421 * operation, receiving repeated calls to SDL_AppIterate and SDL_AppEvent for
|
|
|
422 * the life of the program. If this function returns SDL_APP_FAILURE, SDL will
|
|
|
423 * call SDL_AppQuit and terminate the process with an exit code that reports
|
|
|
424 * an error to the platform. If it returns SDL_APP_SUCCESS, SDL calls
|
|
|
425 * SDL_AppQuit and terminates with an exit code that reports success to the
|
|
|
426 * platform.
|
|
|
427 *
|
|
|
428 * \param appstate an optional pointer, provided by the app in SDL_AppInit.
|
|
|
429 * \param event the new event for the app to examine.
|
|
|
430 * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to
|
|
|
431 * terminate with success, SDL_APP_CONTINUE to continue.
|
|
|
432 *
|
|
|
433 * \threadsafety This function may get called concurrently with
|
|
|
434 * SDL_AppIterate() or SDL_AppQuit() for events not pushed from
|
|
|
435 * the main thread.
|
|
|
436 *
|
|
|
437 * \since This function is available since SDL 3.2.0.
|
|
|
438 *
|
|
|
439 * \sa SDL_AppInit
|
|
|
440 * \sa SDL_AppIterate
|
|
|
441 */
|
|
|
442 extern SDLMAIN_DECLSPEC SDL_AppResult SDLCALL SDL_AppEvent(void *appstate, SDL_Event *event);
|
|
|
443
|
|
|
444 /**
|
|
|
445 * App-implemented deinit entry point for SDL_MAIN_USE_CALLBACKS apps.
|
|
|
446 *
|
|
|
447 * Apps implement this function when using SDL_MAIN_USE_CALLBACKS. If using a
|
|
|
448 * standard "main" function, you should not supply this.
|
|
|
449 *
|
|
|
450 * This function is called once by SDL before terminating the program.
|
|
|
451 *
|
|
|
452 * This function will be called in all cases, even if SDL_AppInit requests
|
|
|
453 * termination at startup.
|
|
|
454 *
|
|
|
455 * This function should not go into an infinite mainloop; it should
|
|
|
456 * deinitialize any resources necessary, perform whatever shutdown activities,
|
|
|
457 * and return.
|
|
|
458 *
|
|
|
459 * You do not need to call SDL_Quit() in this function, as SDL will call it
|
|
|
460 * after this function returns and before the process terminates, but it is
|
|
|
461 * safe to do so.
|
|
|
462 *
|
|
|
463 * The `appstate` parameter is an optional pointer provided by the app during
|
|
|
464 * SDL_AppInit(). If the app never provided a pointer, this will be NULL. This
|
|
|
465 * function call is the last time this pointer will be provided, so any
|
|
|
466 * resources to it should be cleaned up here.
|
|
|
467 *
|
|
|
468 * This function is called by SDL on the main thread.
|
|
|
469 *
|
|
|
470 * \param appstate an optional pointer, provided by the app in SDL_AppInit.
|
|
|
471 * \param result the result code that terminated the app (success or failure).
|
|
|
472 *
|
|
|
473 * \threadsafety SDL_AppEvent() may get called concurrently with this function
|
|
|
474 * if other threads that push events are still active.
|
|
|
475 *
|
|
|
476 * \since This function is available since SDL 3.2.0.
|
|
|
477 *
|
|
|
478 * \sa SDL_AppInit
|
|
|
479 */
|
|
|
480 extern SDLMAIN_DECLSPEC void SDLCALL SDL_AppQuit(void *appstate, SDL_AppResult result);
|
|
|
481
|
|
|
482 #endif /* SDL_MAIN_USE_CALLBACKS */
|
|
|
483
|
|
|
484
|
|
|
485 /**
|
|
|
486 * The prototype for the application's main() function
|
|
|
487 *
|
|
|
488 * \param argc an ANSI-C style main function's argc.
|
|
|
489 * \param argv an ANSI-C style main function's argv.
|
|
|
490 * \returns an ANSI-C main return code; generally 0 is considered successful
|
|
|
491 * program completion, and small non-zero values are considered
|
|
|
492 * errors.
|
|
|
493 *
|
|
|
494 * \since This datatype is available since SDL 3.2.0.
|
|
|
495 */
|
|
|
496 typedef int (SDLCALL *SDL_main_func)(int argc, char *argv[]);
|
|
|
497
|
|
|
498 /**
|
|
|
499 * An app-supplied function for program entry.
|
|
|
500 *
|
|
|
501 * Apps do not directly create this function; they should create a standard
|
|
|
502 * ANSI-C `main` function instead. If SDL needs to insert some startup code
|
|
|
503 * before `main` runs, or the platform doesn't actually _use_ a function
|
|
|
504 * called "main", SDL will do some macro magic to redefine `main` to
|
|
|
505 * `SDL_main` and provide its own `main`.
|
|
|
506 *
|
|
|
507 * Apps should include `SDL_main.h` in the same file as their `main` function,
|
|
|
508 * and they should not use that symbol for anything else in that file, as it
|
|
|
509 * might get redefined.
|
|
|
510 *
|
|
|
511 * This function is only provided by the app if it isn't using
|
|
|
512 * SDL_MAIN_USE_CALLBACKS.
|
|
|
513 *
|
|
|
514 * Program startup is a surprisingly complex topic. Please see
|
|
|
515 * [README-main-functions](README-main-functions), (or
|
|
|
516 * docs/README-main-functions.md in the source tree) for a more detailed
|
|
|
517 * explanation.
|
|
|
518 *
|
|
|
519 * \param argc an ANSI-C style main function's argc.
|
|
|
520 * \param argv an ANSI-C style main function's argv.
|
|
|
521 * \returns an ANSI-C main return code; generally 0 is considered successful
|
|
|
522 * program completion, and small non-zero values are considered
|
|
|
523 * errors.
|
|
|
524 *
|
|
|
525 * \threadsafety This is the program entry point.
|
|
|
526 *
|
|
|
527 * \since This function is available since SDL 3.2.0.
|
|
|
528 */
|
|
|
529 extern SDLMAIN_DECLSPEC int SDLCALL SDL_main(int argc, char *argv[]);
|
|
|
530
|
|
|
531 /**
|
|
|
532 * Circumvent failure of SDL_Init() when not using SDL_main() as an entry
|
|
|
533 * point.
|
|
|
534 *
|
|
|
535 * This function is defined in SDL_main.h, along with the preprocessor rule to
|
|
|
536 * redefine main() as SDL_main(). Thus to ensure that your main() function
|
|
|
537 * will not be changed it is necessary to define SDL_MAIN_HANDLED before
|
|
|
538 * including SDL.h.
|
|
|
539 *
|
|
|
540 * \since This function is available since SDL 3.2.0.
|
|
|
541 *
|
|
|
542 * \sa SDL_Init
|
|
|
543 */
|
|
|
544 extern SDL_DECLSPEC void SDLCALL SDL_SetMainReady(void);
|
|
|
545
|
|
|
546 /**
|
|
|
547 * Initializes and launches an SDL application, by doing platform-specific
|
|
|
548 * initialization before calling your mainFunction and cleanups after it
|
|
|
549 * returns, if that is needed for a specific platform, otherwise it just calls
|
|
|
550 * mainFunction.
|
|
|
551 *
|
|
|
552 * You can use this if you want to use your own main() implementation without
|
|
|
553 * using SDL_main (like when using SDL_MAIN_HANDLED). When using this, you do
|
|
|
554 * *not* need SDL_SetMainReady().
|
|
|
555 *
|
|
|
556 * If `argv` is NULL, SDL will provide command line arguments, either by
|
|
|
557 * querying the OS for them if possible, or supplying a filler array if not.
|
|
|
558 *
|
|
|
559 * \param argc the argc parameter from the application's main() function, or 0
|
|
|
560 * if the platform's main-equivalent has no argc.
|
|
|
561 * \param argv the argv parameter from the application's main() function, or
|
|
|
562 * NULL if the platform's main-equivalent has no argv.
|
|
|
563 * \param mainFunction your SDL app's C-style main(). NOT the function you're
|
|
|
564 * calling this from! Its name doesn't matter; it doesn't
|
|
|
565 * literally have to be `main`.
|
|
|
566 * \param reserved should be NULL (reserved for future use, will probably be
|
|
|
567 * platform-specific then).
|
|
|
568 * \returns the return value from mainFunction: 0 on success, otherwise
|
|
|
569 * failure; SDL_GetError() might have more information on the
|
|
|
570 * failure.
|
|
|
571 *
|
|
|
572 * \threadsafety Generally this is called once, near startup, from the
|
|
|
573 * process's initial thread.
|
|
|
574 *
|
|
|
575 * \since This function is available since SDL 3.2.0.
|
|
|
576 */
|
|
|
577 extern SDL_DECLSPEC int SDLCALL SDL_RunApp(int argc, char *argv[], SDL_main_func mainFunction, void *reserved);
|
|
|
578
|
|
|
579 /**
|
|
|
580 * An entry point for SDL's use in SDL_MAIN_USE_CALLBACKS.
|
|
|
581 *
|
|
|
582 * Generally, you should not call this function directly. This only exists to
|
|
|
583 * hand off work into SDL as soon as possible, where it has a lot more control
|
|
|
584 * and functionality available, and make the inline code in SDL_main.h as
|
|
|
585 * small as possible.
|
|
|
586 *
|
|
|
587 * Not all platforms use this, it's actual use is hidden in a magic
|
|
|
588 * header-only library, and you should not call this directly unless you
|
|
|
589 * _really_ know what you're doing.
|
|
|
590 *
|
|
|
591 * \param argc standard Unix main argc.
|
|
|
592 * \param argv standard Unix main argv.
|
|
|
593 * \param appinit the application's SDL_AppInit function.
|
|
|
594 * \param appiter the application's SDL_AppIterate function.
|
|
|
595 * \param appevent the application's SDL_AppEvent function.
|
|
|
596 * \param appquit the application's SDL_AppQuit function.
|
|
|
597 * \returns standard Unix main return value.
|
|
|
598 *
|
|
|
599 * \threadsafety It is not safe to call this anywhere except as the only
|
|
|
600 * function call in SDL_main.
|
|
|
601 *
|
|
|
602 * \since This function is available since SDL 3.2.0.
|
|
|
603 */
|
|
|
604 extern SDL_DECLSPEC int SDLCALL SDL_EnterAppMainCallbacks(int argc, char *argv[], SDL_AppInit_func appinit, SDL_AppIterate_func appiter, SDL_AppEvent_func appevent, SDL_AppQuit_func appquit);
|
|
|
605
|
|
|
606
|
|
|
607 #if defined(SDL_PLATFORM_WINDOWS)
|
|
|
608
|
|
|
609 /**
|
|
|
610 * Register a win32 window class for SDL's use.
|
|
|
611 *
|
|
|
612 * This can be called to set the application window class at startup. It is
|
|
|
613 * safe to call this multiple times, as long as every call is eventually
|
|
|
614 * paired with a call to SDL_UnregisterApp, but a second registration attempt
|
|
|
615 * while a previous registration is still active will be ignored, other than
|
|
|
616 * to increment a counter.
|
|
|
617 *
|
|
|
618 * Most applications do not need to, and should not, call this directly; SDL
|
|
|
619 * will call it when initializing the video subsystem.
|
|
|
620 *
|
|
|
621 * If `name` is NULL, SDL currently uses `(CS_BYTEALIGNCLIENT | CS_OWNDC)` for
|
|
|
622 * the style, regardless of what is specified here.
|
|
|
623 *
|
|
|
624 * \param name the window class name, in UTF-8 encoding. If NULL, SDL
|
|
|
625 * currently uses "SDL_app" but this isn't guaranteed.
|
|
|
626 * \param style the value to use in WNDCLASSEX::style.
|
|
|
627 * \param hInst the HINSTANCE to use in WNDCLASSEX::hInstance. If zero, SDL
|
|
|
628 * will use `GetModuleHandle(NULL)` instead.
|
|
|
629 * \returns true on success or false on failure; call SDL_GetError() for more
|
|
|
630 * information.
|
|
|
631 *
|
|
|
632 * \since This function is available since SDL 3.2.0.
|
|
|
633 */
|
|
|
634 extern SDL_DECLSPEC bool SDLCALL SDL_RegisterApp(const char *name, Uint32 style, void *hInst);
|
|
|
635
|
|
|
636 /**
|
|
|
637 * Deregister the win32 window class from an SDL_RegisterApp call.
|
|
|
638 *
|
|
|
639 * This can be called to undo the effects of SDL_RegisterApp.
|
|
|
640 *
|
|
|
641 * Most applications do not need to, and should not, call this directly; SDL
|
|
|
642 * will call it when deinitializing the video subsystem.
|
|
|
643 *
|
|
|
644 * It is safe to call this multiple times, as long as every call is eventually
|
|
|
645 * paired with a prior call to SDL_RegisterApp. The window class will only be
|
|
|
646 * deregistered when the registration counter in SDL_RegisterApp decrements to
|
|
|
647 * zero through calls to this function.
|
|
|
648 *
|
|
|
649 * \since This function is available since SDL 3.2.0.
|
|
|
650 */
|
|
|
651 extern SDL_DECLSPEC void SDLCALL SDL_UnregisterApp(void);
|
|
|
652
|
|
|
653 #endif /* defined(SDL_PLATFORM_WINDOWS) */
|
|
|
654
|
|
|
655 /**
|
|
|
656 * Callback from the application to let the suspend continue.
|
|
|
657 *
|
|
|
658 * This function is only needed for Xbox GDK support; all other platforms will
|
|
|
659 * do nothing and set an "unsupported" error message.
|
|
|
660 *
|
|
|
661 * \since This function is available since SDL 3.2.0.
|
|
|
662 */
|
|
|
663 extern SDL_DECLSPEC void SDLCALL SDL_GDKSuspendComplete(void);
|
|
|
664
|
|
|
665 #ifdef __cplusplus
|
|
|
666 }
|
|
|
667 #endif
|
|
|
668
|
|
|
669 #include <SDL3/SDL_close_code.h>
|
|
|
670
|
|
|
671 #if !defined(SDL_MAIN_HANDLED) && !defined(SDL_MAIN_NOIMPL)
|
|
|
672 /* include header-only SDL_main implementations */
|
|
|
673 #if defined(SDL_MAIN_USE_CALLBACKS) || defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE)
|
|
|
674 /* platforms which main (-equivalent) can be implemented in plain C */
|
|
|
675 #include <SDL3/SDL_main_impl.h>
|
|
|
676 #endif
|
|
|
677 #endif
|
|
|
678
|
|
|
679 #endif /* SDL_main_h_ */
|
