Application entry points

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

Classes
struct	SDL::AppInterface
	Base class for SDL3PP_MAIN_USE_CLASS_CALLBACKS main callback classes. 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_MAIN_USE_CLASS_CALLBACKS   1
	Inform SDL to use the main class callbacks instead of main.
#define	SDL3PP_DEFINE_CALLBACKS(CLASS)
	Use this to define the callbacks for given class.
#define	SDL3PP_DEFINE_CLASS_CALLBACKS( CLASS, INIT_FLAGS, APPNAME, APPVERSION, APPIDENTIFIER)
	Use this to define the callbacks for given class, with app metadata.

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

Functions
void	SDL::SetMainReady ()
	Circumvent failure of 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 SDL3PP_MAIN_USE_CALLBACKS.
bool	SDL::RegisterApp (StringParam name, Uint32 style, void *hInst)
	Register a win32 window class for SDL's use.
void	SDL::UnregisterApp ()
	Deregister the win32 window class from an RegisterApp call.
void	SDL::GDKSuspendComplete ()
	Callback from the application to let the suspend continue.
virtual SDL::AppResult	SDL::AppInterface::Init ()
	Called to initialize the app.
virtual SDL::AppResult	SDL::AppInterface::Iterate ()
	Called to iterate the app.
virtual SDL::AppResult	SDL::AppInterface::Event (const SDL::Event &ev)
	Called to handle an event.
virtual void	SDL::AppInterface::quit (SDL::AppResult result)
	Called to quit the app.
SDLMAIN_DECLSPEC SDL::AppInterface *SDLCALL	SDL_AppCreate (int argc, char *argv[])
	Prototype for the application's main class creation function.

Detailed Description

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:

#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:

extern "C" SDLMAIN_DECLSPEC SDL::AppInterface* SDLCALL SDL_AppCreate(        \
  int, char*[])                                                              \
{                                                                            \
  return new CLASS();                                                        \
}

Use this to define the callbacks for given class.

Parameters

CLASS

The class to wrap in callbacks.

SDL3PP_DEFINE_CLASS_CALLBACKS

#define SDL3PP_DEFINE_CLASS_CALLBACKS	(		CLASS,
			INIT_FLAGS,
			APPNAME,
			APPVERSION,
			APPIDENTIFIER )

Value:

extern "C" SDLMAIN_DECLSPEC SDL::AppInterface* SDLCALL SDL_AppCreate(        \
  int, char*[])                                                              \
{                                                                            \
  SDL::SetAppMetadata(APPNAME, APPVERSION, APPIDENTIFIER);                   \
  SDL::Init(INIT_FLAGS);                                                     \
  return new CLASS();                                                        \
}

Use this to define the callbacks for given class, with app metadata.

Parameters

CLASS	The class to wrap in callbacks.
INIT_FLAGS	The flags to pass to SDL::Init when initializing the app.
APPNAME	The application name to set in SDL_SetAppMetadata.
APPVERSION	The application version to set in SDL_SetAppMetadata.
APPIDENTIFIER	The application identifier to set in SDL_SetAppMetadata.

SDL3PP_MAIN_HANDLED

#define SDL3PP_MAIN_HANDLED   SDL_MAIN_HANDLED

Inform SDL that the app is providing an entry point instead of SDL.

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](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

Inform SDL to use the main callbacks instead of main.

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](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

SDL3PP_MAIN_USE_CLASS_CALLBACKS

#define SDL3PP_MAIN_USE_CLASS_CALLBACKS   1

Inform SDL to use the main class callbacks instead of main.

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 a function: SDL_AppCreate. The app should not provide a main function in this case, and doing so will likely cause the build to fail.

Todo

Since

This macro is used by the headers since SDLpp 0.11.0.

See also

SDL_AppCreate

SDL3PP_MAIN_USE_CALLBACKS

Typedef Documentation

main_func

using SDL::main_func = int(SDLCALL*)(int argc, char* argv[])

The prototype for the application's main() function.

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

An entry point for SDL's use in SDL3PP_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

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.

Event()

virtual SDL::AppResult SDL::AppInterface::Event ( const SDL::Event & ev )

inlinevirtual

Called to handle an event.

This is called when an event is received.

Parameters

ev	The event to handle.

Returns

SDL::APP_CONTINUE to continue running the app, otherwise SDL::APP_SUCCESS to exit with success and SDL::APP_FAILURE to exit with failure.

GDKSuspendComplete()

void SDL::GDKSuspendComplete ( )

inline

Callback from the application to let the suspend continue.

This should be called from an event watch in response to an EVENT_DID_ENTER_BACKGROUND event.

When using SDL_Render, your event watch should be added after creating the Renderer; this allows the timing of the D3D12 command queue suspension to execute in the correct order.

When using SDL_GPU, this should be called after calling GPUDevice.GDKSuspendGPU.

If you're writing your own D3D12 renderer, this should be called after calling ID3D12CommandQueue::SuspendX.

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

Thread safety:

This function is not thread safe.

Since

This function is available since SDL 3.2.0.

See also

AddEventWatch

Init()

virtual SDL::AppResult SDL::AppInterface::Init ( )

inlinevirtual

Called to initialize the app.

This is called once at startup.

Returns

SDL::APP_CONTINUE to continue running the app, otherwise SDL::APP_SUCCESS to exit with success and SDL::APP_FAILURE to exit with failure.

Iterate()

virtual SDL::AppResult SDL::AppInterface::Iterate ( )

inlinevirtual

Called to iterate the app.

This is called repeatedly until it returns something other than SDL::APP_CONTINUE.

Returns

SDL::APP_CONTINUE to continue running the app, otherwise SDL::APP_SUCCESS to exit with success and SDL::APP_FAILURE to exit with failure.

quit()

virtual void SDL::AppInterface::quit ( SDL::AppResult result )

inlinevirtual

Called to quit the app.

This is called when the app is quitting.

Parameters

result

The result of the app.

RegisterApp()

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

inline

Register a win32 window class for SDL's use.

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.

Thread safety:

This function is not thread safe.

Since

This function is available since SDL 3.2.0.

RunApp()

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

inline

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 SDL3PP_MAIN_HANDLED). When using this, you do not need SetMainReady().

If argv is nullptr, SDL will provide command line arguments, either by querying the OS for them if possible, or supplying a filler array if not.

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.

SDL_AppCreate()

SDLMAIN_DECLSPEC SDL::AppInterface *SDLCALL SDL_AppCreate	(	int	argc,
		char *	argv[] )

Prototype for the application's main class creation function.

You need to implement this function if you want to use SDL3PP_MAIN_USE_CLASS_CALLBACKS. It should return a pointer to an instance of your main class, which should be a subclass of AppInterface. This function is called by SDL to create the main class instance, and then SDL will call the appropriate functions on that instance for initialization, iteration, event handling, and quitting.

You should not call this function directly; it is called by SDL3pp internally.

You may also use the macros SDL3PP_DEFINE_CALLBACKS or SDL3PP_DEFINE_CLASS_CALLBACKS to define this function for you, if your main class is compatible with the default implementations of the main callbacks.

#define SDL3PP_MAIN_USE_CLASS_CALLBACKS
#include <SDL3pp/SDL3pp_main.h>
#include <SDL3pp/SDL3pp.h>
 
class Main: public SDL::AppInterface {
}
 
SDL::AppInterface *SDL_AppCreate(int argc, char *argv[]) {
  return new Main();
}

Parameters

argc	an ANSI-C style main function's argc.
argv	an ANSI-C style main function's argv.

Returns

a pointer to the application's main class instance, or nullptr to indicate early exit with APP_SUCCESS.

Exceptions

any	exception, which will be caught and logged by SDL, and cause the app to exit with APP_FAILURE.

Since

This function is available since SDL3pp 0.10.1.

See also

SDL3PP_DEFINE_CALLBACKS

SDL3PP_DEFINE_CLASS_CALLBACKS

SetMainReady()

void SDL::SetMainReady ( )

inline

Circumvent failure of 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 SDL3PP_MAIN_HANDLED before including SDL.h.

Thread safety:

This function is not thread safe.

Since

This function is available since SDL 3.2.0.

See also

Init

UnregisterApp()

void SDL::UnregisterApp ( )

inline

Deregister the win32 window class from an RegisterApp call.

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.

Thread safety:

This function is not thread safe.

Since

This function is available since SDL 3.2.0.