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

Collaboration diagram for Application entry points:

Macros
#define	SDL3PP_MAIN_HANDLED SDL_MAIN_HANDLED
	Inform SDL that the app is providing an entry point instead of SDL. More...

#define	SDL3PP_MAIN_USE_CALLBACKS SDL_MAIN_USE_CALLBACKS
	Inform SDL to use the main callbacks instead of main. More...

#define	SDL3PP_DEFINE_CALLBACKS(CLASS)
	Use this to define the callbacks for given class. More...

Typedefs
using	SDL::main_func = int(SDLCALL )(int argc, char argv[])
	The prototype for the application's main() function. More...

Functions
void	SDL::SetMainReady ()
	Circumvent failure of Init() when not using SDL_main() as an entry point. More...

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

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 SDL3PP_MAIN_USE_CALLBACKS. More...

bool	SDL::RegisterApp (StringParam name, Uint32 style, void *hInst)
	Register a win32 window class for SDL's use. More...

void	SDL::UnregisterApp ()
	Deregister the win32 window class from an RegisterApp call. More...

void	SDL::GDKSuspendComplete ()
	Callback from the application to let the suspend continue. More...

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 SDL3PP_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 )

Value:

  static_assert(SDL::HasIterateFunction<CLASS>, "Main class not compatible");  \
  inline SDL::AppResult SDL_AppInit(void** appstate, int argc, char* argv[])   \
  {                                                                            \
    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.

◆ 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 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 int(SDLCALL*)(int argc, char* argv[])

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.

◆ RegisterApp()

bool SDL::RegisterApp	(	StringParam	name,
		Uint32	style,
		void *	hInst
	)

inline

This can be called to set the application window class at startup. It is safe to call this multiple times, as long as every call is eventually paired with a call to UnregisterApp, but a second registration attempt while a previous registration is still active will be ignored, other than to increment a counter.

Most applications do not need to, and should not, call this directly; SDL will call it when initializing the video subsystem.

Parameters

name	the window class name, in UTF-8 encoding. If nullptr, SDL currently uses "SDL_app" but this isn't guaranteed.
style	the value to use in WNDCLASSEX::style. If `name` is nullptr, SDL currently uses `(CS_BYTEALIGNCLIENT \| CS_OWNDC)` regardless of what is specified here.
hInst	the HINSTANCE to use in WNDCLASSEX::hInstance. If zero, SDL will use `GetModuleHandle(nullptr)` instead.

Returns: true on success or false on failure; call GetError() for more information.

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 SDL3PP_MAIN_HANDLED). When using this, you do not need 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 nullptr 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 nullptr (reserved for future use, will probably be platform-specific then).

Returns: the return value from mainFunction: 0 on success, otherwise failure; 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 SDL3PP_MAIN_HANDLED before including SDL.h.

Since: This function is available since SDL 3.2.0.

See also: Init

◆ UnregisterApp()

void SDL::UnregisterApp ( )

inline

This can be called to undo the effects of RegisterApp.

Most applications do not need to, and should not, call this directly; SDL will call it when deinitializing the video subsystem.

It is safe to call this multiple times, as long as every call is eventually paired with a prior call to RegisterApp. The window class will only be deregistered when the registration counter in RegisterApp decrements to zero through calls to this function.

Since: This function is available since SDL 3.2.0.

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SDL3PP_DEFINE_CALLBACKS

◆ SDL3PP_MAIN_HANDLED

◆ SDL3PP_MAIN_USE_CALLBACKS

Typedef Documentation

◆ main_func

Function Documentation

◆ EnterAppMainCallbacks()

◆ GDKSuspendComplete()

◆ RegisterApp()

◆ RunApp()

◆ SetMainReady()

◆ UnregisterApp()