SDL 3.0
SDL_main.h File Reference
+ Include dependency graph for SDL_main.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define SDLMAIN_DECLSPEC
 

Typedefs

typedef int(* SDL_main_func) (int argc, char *argv[])
 

Functions

SDLMAIN_DECLSPEC int SDL_main (int argc, char *argv[])
 
void SDL_SetMainReady (void)
 
int SDL_RunApp (int argc, char *argv[], SDL_main_func mainFunction, void *reserved)
 
int SDL_EnterAppMainCallbacks (int argc, char *argv[], SDL_AppInit_func appinit, SDL_AppIterate_func appiter, SDL_AppEvent_func appevent, SDL_AppQuit_func appquit)
 
void SDL_GDKSuspendComplete (void)
 

Macro Definition Documentation

◆ SDLMAIN_DECLSPEC

#define SDLMAIN_DECLSPEC

CategoryMain

Redefine main() if necessary so that it is called by SDL.

In order to make this consistent on all platforms, the application's main() should look like this:

int main(int argc, char *argv[])
{
}
#define main

SDL will take care of platform specific details on how it gets called.

This is also where an app can be configured to use the main callbacks, via the SDL_MAIN_USE_CALLBACKS macro.

This is a "single-header library," which is to say that including this header inserts code into your program, and you should only include it once in most cases. SDL.h does not include this header automatically.

For more information, see:

https://wiki.libsdl.org/SDL3/README/main-functions

Definition at line 250 of file SDL_main.h.

Typedef Documentation

◆ SDL_main_func

typedef int(* SDL_main_func) (int argc, char *argv[])

The prototype for the application's main() function

Parameters
argcan ANSI-C style main function's argc.
argvan ANSI-C style main function's argv.
Returns
an ANSI-C main return code; generally 0 is considered successful program completion, and small non-zero values are considered errors.
Since
This datatype is available since SDL 3.1.3.

Definition at line 487 of file SDL_main.h.

Function Documentation

◆ SDL_EnterAppMainCallbacks()

int SDL_EnterAppMainCallbacks ( int  argc,
char *  argv[],
SDL_AppInit_func  appinit,
SDL_AppIterate_func  appiter,
SDL_AppEvent_func  appevent,
SDL_AppQuit_func  appquit 
)
extern

An entry point for SDL's use in SDL_MAIN_USE_CALLBACKS.

Generally, you should not call this function directly. This only exists to hand off work into SDL as soon as possible, where it has a lot more control and functionality available, and make the inline code in SDL_main.h as small as possible.

Not all platforms use this, it's actual use is hidden in a magic header-only library, and you should not call this directly unless you really know what you're doing.

Parameters
argcstandard Unix main argc.
argvstandard Unix main argv.
appinitthe application's SDL_AppInit function.
appiterthe application's SDL_AppIterate function.
appeventthe application's SDL_AppEvent function.
appquitthe application's SDL_AppQuit function.
Returns
standard Unix main return value.

\threadsafety It is not safe to call this anywhere except as the only function call in SDL_main.

Since
This function is available since SDL 3.1.3.

◆ SDL_GDKSuspendComplete()

void SDL_GDKSuspendComplete ( void  )
extern

Callback from the application to let the suspend continue.

This function is only needed for Xbox GDK support; all other platforms will do nothing and set an "unsupported" error message.

Since
This function is available since SDL 3.1.3.

◆ SDL_main()

SDLMAIN_DECLSPEC int SDL_main ( int  argc,
char *  argv[] 
)
extern

An app-supplied function for program entry.

Apps do not directly create this function; they should create a standard ANSI-C main function instead. If SDL needs to insert some startup code before main runs, or the platform doesn't actually use a function called "main", SDL will do some macro magic to redefine main to SDL_main and provide its own main.

Apps should include SDL_main.h in the same file as their main function, and they should not use that symbol for anything else in that file, as it might get redefined.

This function is only provided by the app if it isn't using SDL_MAIN_USE_CALLBACKS.

Program startup is a surprisingly complex topic. Please see README/main-functions, (or docs/README-main-functions.md in the source tree) for a more detailed explanation.

Parameters
argcan ANSI-C style main function's argc.
argvan ANSI-C style main function's argv.
Returns
an ANSI-C main return code; generally 0 is considered successful program completion, and small non-zero values are considered errors.

\threadsafety This is the program entry point.

Since
This function is available since SDL 3.1.3.

Referenced by main().

◆ SDL_RunApp()

int SDL_RunApp ( int  argc,
char *  argv[],
SDL_main_func  mainFunction,
void *  reserved 
)
extern

Initializes and launches an SDL application, by doing platform-specific initialization before calling your mainFunction and cleanups after it returns, if that is needed for a specific platform, otherwise it just calls mainFunction.

You can use this if you want to use your own main() implementation without using SDL_main (like when using SDL_MAIN_HANDLED). When using this, you do not need SDL_SetMainReady().

Parameters
argcthe argc parameter from the application's main() function, or 0 if the platform's main-equivalent has no argc.
argvthe argv parameter from the application's main() function, or NULL if the platform's main-equivalent has no argv.
mainFunctionyour SDL app's C-style main(). NOT the function you're calling this from! Its name doesn't matter; it doesn't literally have to be main.
reservedshould be NULL (reserved for future use, will probably be platform-specific then).
Returns
the return value from mainFunction: 0 on success, otherwise failure; SDL_GetError() might have more information on the failure.

\threadsafety Generally this is called once, near startup, from the process's initial thread.

Since
This function is available since SDL 3.1.3.

Referenced by main().

◆ SDL_SetMainReady()

void SDL_SetMainReady ( void  )
extern

Circumvent failure of SDL_Init() when not using SDL_main() as an entry point.

This function is defined in SDL_main.h, along with the preprocessor rule to redefine main() as SDL_main(). Thus to ensure that your main() function will not be changed it is necessary to define SDL_MAIN_HANDLED before including SDL.h.

Since
This function is available since SDL 3.1.3.
See also
SDL_Init