Application entry points

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

Macros
#define	SDL3PP_MAIN_HANDLED   SDL_MAIN_HANDLED
	Inform SDL that the app is providing an entry point instead of SDL.
#define	SDL3PP_MAIN_USE_CALLBACKS   SDL_MAIN_USE_CALLBACKS
	Inform SDL to use the main callbacks instead of main.
#define	SDL3PP_DEFINE_CALLBACKS(CLASS, APPNAME, APPVERSION, APPID)
	Use this to define the callbacks for given class.

Typedefs
using	SDL::main_func = SDL_main_func
	The prototype for the application's main() function.

Functions
void	SDL::SetMainReady ()
	Circumvent failure of SDL_Init() when not using SDL_main() as an entry point.
int	SDL::RunApp (int argc, char *argv[], main_func mainFunction, void *reserved)
	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.
int	SDL::EnterAppMainCallbacks (int argc, char *argv[], AppInit_func appinit, AppIterate_func appiter, AppEvent_func appevent, AppQuit_func appquit)
	An entry point for SDL's use in SDL_MAIN_USE_CALLBACKS.
void	SDL::GDKSuspendComplete ()
	Callback from the application to let the suspend continue.

Detailed Description

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

#include <SDL3pp/SDL3pp.h>
#include <SDL3pp/SDL3pp_main.h>
 
int main(int argc, char *argv[])
{
}

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.

SDL_main.h 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

Macro Definition Documentation

SDL3PP_DEFINE_CALLBACKS

#define SDL3PP_DEFINE_CALLBACKS	(		CLASS,
			APPNAME,
			APPVERSION,
			APPID
	)

Value:

  static_assert(SDL::HasIterateFunction<CLASS>, "Main class not compatible");  \
  inline SDL::AppResult SDL_AppInit(void** appstate, int argc, char* argv[])   \
  {                                                                            \
    if (APPNAME) {                                                             \
      SDL::SetAppMetadata(APPNAME, APPVERSION ?: "1.0", APPID ?: APPNAME);     \
    }                                                                          \
    return SDL::InitClass(reinterpret_cast<CLASS**>(appstate),                 \
                          SDL::AppArgs{argv, size_t(argc)});                   \
  }                                                                            \
  inline SDL::AppResult SDL_AppIterate(void* appstate)                         \
  {                                                                            \
    return SDL::IterateClass(static_cast<CLASS*>(appstate));                   \
  }                                                                            \
  inline SDL::AppResult SDL_AppEvent(void* appstate, SDL::Event* event)        \
  {                                                                            \
    return SDL::EventClass(static_cast<CLASS*>(appstate), *event);             \
  }                                                                            \
  inline void SDL_AppQuit(void* appstate, SDL::AppResult result)               \
  {                                                                            \
    SDL::QuitClass(static_cast<CLASS*>(appstate), result);                     \
  }

Parameters

CLASS	The class to wrap in callbacks.
APPNAME	the app name. If not nullptr it calls SetAppMetadata to initialize. If nullptr the user is responsible to set it.
APPVERSION	the app version. If nullptr defaults to "1.0".
APPID	The app id. If nullptr it defaults to APPNAME.

SDL3PP_MAIN_HANDLED

#define SDL3PP_MAIN_HANDLED   SDL_MAIN_HANDLED

SDL does not define this macro, but will check if it is defined when including SDL_main.h. If defined, SDL will expect the app to provide the proper entry point for the platform, and all the other magic details needed, like manually calling SDL_SetMainReady.

Please see README/main-functions, (or docs/README-main-functions.md in the source tree) for a more detailed explanation.

Since

This macro is used by the headers since SDL 3.2.0.

SDL3PP_MAIN_USE_CALLBACKS

#define SDL3PP_MAIN_USE_CALLBACKS   SDL_MAIN_USE_CALLBACKS

SDL does not define this macro, but will check if it is defined when including SDL_main.h. If defined, SDL will expect the app to provide several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and SDL_AppQuit. The app should not provide a main function in this case, and doing so will likely cause the build to fail.

Please see README/main-functions, (or docs/README-main-functions.md in the source tree) for a more detailed explanation.

Since

This macro is used by the headers since SDL 3.2.0.

See also

SDL_AppInit

SDL_AppEvent

SDL_AppIterate

SDL_AppQuit

Typedef Documentation

main_func

using SDL::main_func = typedef SDL_main_func

Parameters

argc	an ANSI-C style main function's argc.
argv	an 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.2.0.

Function Documentation

EnterAppMainCallbacks()

int SDL::EnterAppMainCallbacks ( int  argc, char *  argv[], AppInit_func  appinit, AppIterate_func  appiter, AppEvent_func  appevent, AppQuit_func  appquit  )

inline

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

argc	standard Unix main argc.
argv	standard Unix main argv.
appinit	the application's SDL_AppInit function.
appiter	the application's SDL_AppIterate function.
appevent	the application's SDL_AppEvent function.
appquit	the application's SDL_AppQuit function.

Returns

standard Unix main return value.

Thread safety:

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.2.0.

GDKSuspendComplete()

void SDL::GDKSuspendComplete ( )

inline

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.2.0.

RunApp()

int SDL::RunApp ( int  argc, char *  argv[], main_func  mainFunction, void *  reserved  )

inline

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

argc	the argc parameter from the application's main() function, or 0 if the platform's main-equivalent has no argc.
argv	the argv parameter from the application's main() function, or NULL if the platform's main-equivalent has no argv.
mainFunction	your 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.
reserved	should 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.

Thread safety:

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

Since

This function is available since SDL 3.2.0.

SetMainReady()

void SDL::SetMainReady ( )

inline

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.2.0.

See also

SDL_Init