All SDL programs need to initialize the library before starting to work with it. More...

Topics
	Initialization flags

Concepts
concept	SDL::HasInitFunction
concept	SDL::HasIterateFunction
concept	SDL::HasEventFunction
concept	SDL::HasQuitFunction

Macros
#define	SDL3PP_APPCLASS_LOG_PRIORITY LOG_PRIORITY_CRITICAL
	The default log priority for app class.

Typedefs
using	SDL::AppArgs = std::span<char const* const>
	Represents application parameters.

Functions
void	SDL::Init (InitFlags flags)
	Initialize the SDL library.
void	SDL::InitSubSystem (InitFlags flags)
	Compatibility function to initialize the SDL library.
void	SDL::QuitSubSystem (InitFlags flags)
	Shut down specific SDL subsystems.
InitFlags	SDL::WasInit (InitFlags flags)
	Get a mask of the specified subsystems which are currently initialized.
void	SDL::Quit ()
	Clean up all initialized subsystems.
bool	SDL::IsMainThread ()
	Return whether this is the main thread.
void	SDL::RunOnMainThread (MainThreadCallback callback, void *userdata, bool wait_complete)
	Call a function on the main thread during event processing.
void	SDL::RunOnMainThread (MainThreadCB callback, bool wait_complete)
	Call a function on the main thread during event processing.
void	SDL::SetAppMetadata (StringParam appname, StringParam appversion, StringParam appidentifier)
	Specify basic metadata about your app.
void	SDL::SetAppMetadataProperty (StringParam name, StringParam value)
	Specify metadata about your app through a set of properties.
const char *	SDL::GetAppMetadataProperty (StringParam name)
	Get metadata about your app.
template<HasIterateFunction T>
AppResult	SDL::IterateClass (T *state)
	Iterate the state.
template<class T>
AppResult	SDL::DefaultEventClass (T *, const SDL_Event &event)
	Default handle by finishing if QUIT is requested.
template<class T>
void	SDL::DefaultClassDestroy (T *state)
	Destroy state with delete;.

AppResult
App result for Main callback
using	SDL::AppResult = SDL_AppResult
	Return values for optional main callbacks.
constexpr AppResult	SDL::APP_CONTINUE = SDL_APP_CONTINUE
	Value that requests that the app continue from the main callbacks.
constexpr AppResult	SDL::APP_SUCCESS = SDL_APP_SUCCESS
	Value that requests termination with success from the main callbacks.
constexpr AppResult	SDL::APP_FAILURE = SDL_APP_FAILURE
	Value that requests termination with error from the main callbacks.

Callbacks for EnterAppMainCallbacks()
using	SDL::AppInit_func
	Function pointer typedef for SDL_AppInit.
using	SDL::AppIterate_func = AppResult(SDLCALL)(void appstate)
	Function pointer typedef for SDL_AppIterate.
using	SDL::AppEvent_func = AppResult(SDLCALL)(void appstate, Event* event)
	Function pointer typedef for SDL_AppEvent.
using	SDL::AppQuit_func = void(SDLCALL)(void appstate, AppResult result)
	Function pointer typedef for SDL_AppQuit.

Callbacks for RunOnMainThread()
using	SDL::MainThreadCallback = void(SDLCALL)(void userdata)
	Callback run on the main thread.
using	SDL::MainThreadCB = std::function<void()>
	Callback run on the main thread.
template<class T>
AppResult	SDL::DefaultCreateClass (T **state, AppArgs args)
	Allocate and initialize state with new.
template<class T>
AppResult	SDL::InitClass (T **state, AppArgs args)
	Init state with arguments.
template<class T>
AppResult	SDL::EventClass (T *state, const SDL_Event &event)
	Iterate the state.
template<class T>
void	SDL::QuitClass (T *state, AppResult)
	Destroy state with given result.

Detailed Description

All SDL programs need to initialize the library before starting to work with it.

Almost everything can simply call Init() near startup, with a handful of flags to specify subsystems to touch. These are here to make sure SDL does not even attempt to touch low-level pieces of the operating system that you don't intend to use. For example, you might be using SDL for video and input but chose an external library for audio, and in this case you would just need to leave off the INIT_AUDIO flag to make sure that external library has complete control.

Most apps, when terminating, should call Quit(). This will clean up (nearly) everything that SDL might have allocated, and crucially, it'll make sure that the display's resolution is back to what the user expects if you had previously changed it for your game.

SDL3 apps are strongly encouraged to call SetAppMetadata() at startup to fill in details about the program. This is completely optional, but it helps in small ways (we can provide an About dialog box for the macOS menu, we can name the app in the system's audio mixer, etc). Those that want to provide a lot of information should look at the more-detailed SetAppMetadataProperty().

Typedef Documentation

◆ AppEvent_func

using SDL::AppEvent_func = AppResult(SDLCALL*)(void* appstate, Event* event)

Function pointer typedef for SDL_AppEvent.

These are used by EnterAppMainCallbacks. This mechanism operates behind the scenes for apps using the optional main callbacks. Apps that want to use this should just implement SDL_AppEvent directly.

Parameters

appstate	an optional pointer, provided by the app in SDL_AppInit.
event	the new event for the app to examine.

Returns: APP_FAILURE to terminate with an error, APP_SUCCESS to terminate with success, APP_CONTINUE to continue.

Since: This datatype is available since SDL 3.2.0.

◆ AppInit_func

using SDL::AppInit_func

Initial value:

AppResult(SDLCALL*)(void** appstate,
                                        int argc,
                                        char* argv[])

Function pointer typedef for SDL_AppInit.

These are used by EnterAppMainCallbacks. This mechanism operates behind the scenes for apps using the optional main callbacks. Apps that want to use this should just implement SDL_AppInit directly.

Parameters

appstate	a place where the app can optionally store a pointer for future use.
argc	the standard ANSI C main's argc; number of elements in argv.
argv	the standard ANSI C main's argv; array of command line arguments.

Returns: APP_FAILURE to terminate with an error, APP_SUCCESS to terminate with success, APP_CONTINUE to continue.

Since: This datatype is available since SDL 3.2.0.

◆ AppIterate_func

using SDL::AppIterate_func = AppResult(SDLCALL*)(void* appstate)

Function pointer typedef for SDL_AppIterate.

These are used by EnterAppMainCallbacks. This mechanism operates behind the scenes for apps using the optional main callbacks. Apps that want to use this should just implement SDL_AppIterate directly.

Parameters

appstate an optional pointer, provided by the app in SDL_AppInit.

Returns: APP_FAILURE to terminate with an error, APP_SUCCESS to terminate with success, APP_CONTINUE to continue.

Since: This datatype is available since SDL 3.2.0.

◆ AppQuit_func

using SDL::AppQuit_func = void(SDLCALL*)(void* appstate, AppResult result)

Function pointer typedef for SDL_AppQuit.

These are used by EnterAppMainCallbacks. This mechanism operates behind the scenes for apps using the optional main callbacks. Apps that want to use this should just implement SDL_AppEvent directly.

Parameters

appstate	an optional pointer, provided by the app in SDL_AppInit.
result	the result code that terminated the app (success or failure).

Since: This datatype is available since SDL 3.2.0.

◆ AppResult

using SDL::AppResult = SDL_AppResult

Return values for optional main callbacks.

Returning APP_SUCCESS or APP_FAILURE from SDL_AppInit, SDL_AppEvent, or SDL_AppIterate will terminate the program and report success/failure to the operating system. What that means is platform-dependent. On Unix, for example, on success, the process error code will be zero, and on failure it will be 1. This interface doesn't allow you to return specific exit codes, just whether there was an error generally or not.

Returning APP_CONTINUE from these functions will let the app continue to run.

See Main callbacks in SDL3 for complete details.

Since: This enum is available since SDL 3.2.0.

◆ MainThreadCallback

using SDL::MainThreadCallback = void(SDLCALL*)(void* userdata)

Callback run on the main thread.

Parameters

userdata an app-controlled pointer that is passed to the callback.

Since: This datatype is available since SDL 3.2.0.

See also: RunOnMainThread

◆ MainThreadCB

using SDL::MainThreadCB = std::function<void()>

Callback run on the main thread.

Since: This datatype is available since SDL 3.2.0.

See also: RunOnMainThread; MainThreadCallback

Category:: Result callback

Function Documentation

◆ DefaultClassDestroy()

template<class T>

void SDL::DefaultClassDestroy ( T * state )

inline

Destroy state with delete;.

Template Parameters

T

Parameters

state

◆ DefaultCreateClass()

template<class T>

AppResult SDL::DefaultCreateClass	(	T **	state,
		AppArgs	args )

inline

Allocate and initialize state with new.

If possible, pass the args to constructor, otherwise expects a default ctor;

Template Parameters

T	the state class

Parameters

state	the state to initialize
args	the program arguments

Returns: the app status

◆ DefaultEventClass()

template<class T>

AppResult SDL::DefaultEventClass	(	T *	,
		const SDL_Event &	event )

inline

Default handle by finishing if QUIT is requested.

Template Parameters

T	the state class

Parameters

event the event

Returns: APP_SUCCESS if event is QUIT_EVENT, APP_CONTINUE otherwise,

◆ EventClass()

template<class T>

AppResult SDL::EventClass	(	T *	state,
		const SDL_Event &	event )

inline

Iterate the state.

Template Parameters

T	the state class

Parameters

state	the state
event	the event to handle

Returns: the app status

◆ GetAppMetadataProperty()

const char * SDL::GetAppMetadataProperty ( StringParam name )

inline

Get metadata about your app.

This returns metadata previously set using SetAppMetadata() or SetAppMetadataProperty(). See SetAppMetadataProperty() for the list of available properties and their meanings.

Parameters

name	the name of the metadata property to get.

Returns: the current value of the metadata property, or the default if it is not set, nullptr for properties with no default.

Thread safety:: It is safe to call this function from any thread, although the string returned is not protected and could potentially be freed if you call SetAppMetadataProperty() to set that property from another thread.

Since: This function is available since SDL 3.2.0.

See also: SetAppMetadata; SetAppMetadataProperty

◆ Init()

void SDL::Init ( InitFlags flags )

inline

Initialize the SDL library.

Init() simply forwards to calling InitSubSystem(). Therefore, the two may be used interchangeably. Though for readability of your code InitSubSystem() might be preferred.

The file I/O (for example: IOStream.FromFile) and threading (CreateThread) subsystems are initialized by default. Message boxes (ShowSimpleMessageBox) also attempt to work without initializing the video subsystem, in hopes of being useful in showing an error dialog when Init fails. You must specifically initialize other subsystems if you use them in your application.

Logging (such as Log) works without initialization, too.

flags may be any of the following OR'd together:

INIT_AUDIO: audio subsystem; automatically initializes the events subsystem
INIT_VIDEO: video subsystem; automatically initializes the events subsystem, should be initialized on the main thread.
INIT_JOYSTICK: joystick subsystem; automatically initializes the events subsystem
INIT_HAPTIC: haptic (force feedback) subsystem
INIT_GAMEPAD: gamepad subsystem; automatically initializes the joystick subsystem
INIT_EVENTS: events subsystem
INIT_SENSOR: sensor subsystem; automatically initializes the events subsystem
INIT_CAMERA: camera subsystem; automatically initializes the events subsystem

Subsystem initialization is ref-counted, you must call QuitSubSystem() for each InitSubSystem() to correctly shutdown a subsystem manually (or call Quit() to force shutdown). If a subsystem is already loaded then this call will increase the ref-count and return.

Consider reporting some basic metadata about your application before calling Init, using either SetAppMetadata() or SetAppMetadataProperty().

Parameters

flags subsystem initialization flags.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: SetAppMetadata; SetAppMetadataProperty; InitSubSystem; Quit; SetMainReady; WasInit

◆ InitClass()

template<class T>

AppResult SDL::InitClass	(	T **	state,
		AppArgs	args )

inline

Init state with arguments.

This will call T::Init() if available, otherwise it delegates to DefaultCreateClass().

Template Parameters

T	the state class

Parameters

state	the state to initialize
args	the program arguments

Returns: the app status

◆ InitSubSystem()

void SDL::InitSubSystem ( InitFlags flags )

inline

Compatibility function to initialize the SDL library.

This function and Init() are interchangeable.

Parameters

flags any of the flags used by Init(); see Init for details.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: Init; Quit; QuitSubSystem

◆ IsMainThread()

bool SDL::IsMainThread ( )

inline

Return whether this is the main thread.

On Apple platforms, the main thread is the thread that runs your program's main() entry point. On other platforms, the main thread is the one that calls Init(INIT_VIDEO), which should usually be the one that runs your program's main() entry point. If you are using the main callbacks, SDL_AppInit(), SDL_AppIterate(), and SDL_AppQuit() are all called on the main thread.

Returns: true if this thread is the main thread, or false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: RunOnMainThread

◆ IterateClass()

template<HasIterateFunction T>

AppResult SDL::IterateClass ( T * state )

inline

Iterate the state.

Template Parameters

T	the state class

Parameters

state the state

Returns: the app status

◆ Quit()

void SDL::Quit ( )

inline

Clean up all initialized subsystems.

You should call this function even if you have already shutdown each initialized subsystem with QuitSubSystem(). It is safe to call this function even in the case of errors in initialization.

You can use this function with atexit() to ensure that it is run when your application is shutdown, but it is not wise to do this from a library or other dynamically loaded code.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: Init; QuitSubSystem

◆ QuitClass()

template<class T>

void SDL::QuitClass	(	T *	state,
		AppResult	)

inline

Destroy state with given result.

This is responsible to destroy and deallocate the state. It tries to call T::Quit() if available and delegates to it the duty of deleting. Otherwise it calls delete directly.

Template Parameters

T	the state class.

Parameters

state	the state to destroy.
result	the app result.

◆ QuitSubSystem()

void SDL::QuitSubSystem ( InitFlags flags )

inline

Shut down specific SDL subsystems.

You still need to call Quit() even if you close all open subsystems with QuitSubSystem().

Parameters

flags any of the flags used by Init(); see Init for details.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: InitSubSystem; Quit

◆ RunOnMainThread() [1/2]

void SDL::RunOnMainThread	(	MainThreadCallback	callback,
		void *	userdata,
		bool	wait_complete )

inline

Call a function on the main thread during event processing.

If this is called on the main thread, the callback is executed immediately. If this is called on another thread, this callback is queued for execution on the main thread during event processing.

Be careful of deadlocks when using this functionality. You should not have the main thread wait for the current thread while this function is being called with wait_complete true.

Parameters

callback	the callback to call on the main thread.
userdata	a pointer that is passed to callback.
wait_complete	true to wait for the callback to complete, false to return immediately.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: IsMainThread

◆ RunOnMainThread() [2/2]

void SDL::RunOnMainThread	(	MainThreadCB	callback,
		bool	wait_complete )

inline

Call a function on the main thread during event processing.

If this is called on the main thread, the callback is executed immediately. If this is called on another thread, this callback is queued for execution on the main thread during event processing.

Be careful of deadlocks when using this functionality. You should not have the main thread wait for the current thread while this function is being called with wait_complete true.

Parameters

callback	the callback to call on the main thread.
wait_complete	true to wait for the callback to complete, false to return immediately.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: IsMainThread; result-callback

Category:: Result callback

◆ SetAppMetadata()

void SDL::SetAppMetadata	(	StringParam	appname,
		StringParam	appversion,
		StringParam	appidentifier )

inline

Specify basic metadata about your app.

You can optionally provide metadata about your app to SDL. This is not required, but strongly encouraged.

There are several locations where SDL can make use of metadata (an "About" box in the macOS menu bar, the name of the app can be shown on some audio mixers, etc). Any piece of metadata can be left as nullptr, if a specific detail doesn't make sense for the app.

This function should be called as early as possible, before Init. Multiple calls to this function are allowed, but various state might not change once it has been set up with a previous call to this function.

Passing a nullptr removes any previous metadata.

This is a simplified interface for the most important information. You can supply significantly more detailed metadata with SetAppMetadataProperty().

Parameters

appname	The name of the application ("My Game 2: Bad Guy's Revenge!").
appversion	The version of the application ("1.0.0beta5" or a git hash, or whatever makes sense).
appidentifier	A unique string in reverse-domain format that identifies this app ("com.example.mygame2").

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: SetAppMetadataProperty

◆ SetAppMetadataProperty()

void SDL::SetAppMetadataProperty	(	StringParam	name,
		StringParam	value )

inline

Specify metadata about your app through a set of properties.

You can optionally provide metadata about your app to SDL. This is not required, but strongly encouraged.

There are several locations where SDL can make use of metadata (an "About" box in the macOS menu bar, the name of the app can be shown on some audio mixers, etc). Any piece of metadata can be left out, if a specific detail doesn't make sense for the app.

This function should be called as early as possible, before Init. Multiple calls to this function are allowed, but various state might not change once it has been set up with a previous call to this function.

Once set, this metadata can be read using GetAppMetadataProperty().

These are the supported properties:

prop::appMetaData.NAME_STRING: The human-readable name of the application, like "My Game 2: Bad Guy's Revenge!". This will show up anywhere the OS shows the name of the application separately from window titles, such as volume control applets, etc. This defaults to "SDL Application".
prop::appMetaData.VERSION_STRING: The version of the app that is running; there are no rules on format, so "1.0.3beta2" and "April 22nd, 2024" and a git hash are all valid options. This has no default.
prop::appMetaData.IDENTIFIER_STRING: A unique string that identifies this app. This must be in reverse-domain format, like "com.example.mygame2". This string is used by desktop compositors to identify and group windows together, as well as match applications with associated desktop settings and icons. If you plan to package your application in a container such as Flatpak, the app ID should match the name of your Flatpak container as well. This has no default.
prop::appMetaData.CREATOR_STRING: The human-readable name of the creator/developer/maker of this app, like "MojoWorkshop, LLC"
prop::appMetaData.COPYRIGHT_STRING: The human-readable copyright notice, like "Copyright (c) 2024 MojoWorkshop, LLC" or whatnot. Keep this to one line, don't paste a copy of a whole software license in here. This has no default.
prop::appMetaData.URL_STRING: A URL to the app on the web. Maybe a product page, or a storefront, or even a GitHub repository, for user's further information This has no default.
prop::appMetaData.TYPE_STRING: The type of application this is. Currently this string can be "game" for a video game, "mediaplayer" for a media player, or generically "application" if nothing else applies. Future versions of SDL might add new types. This defaults to "application".

Parameters

name	the name of the metadata property to set.
value	the value of the property, or nullptr to remove that property.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetAppMetadataProperty; SetAppMetadata

◆ WasInit()

InitFlags SDL::WasInit ( InitFlags flags )

inline

Get a mask of the specified subsystems which are currently initialized.

Parameters

flags any of the flags used by Init(); see Init for details.

Returns: a mask of all initialized subsystems if flags is 0, otherwise it returns the initialization status of the specified subsystems.

Thread safety:: This function is not thread safe.

Since: This function is available since SDL 3.2.0.

See also: Init; InitSubSystem

Topics

Concepts

Macros

Typedefs

Functions

AppResult

Callbacks for EnterAppMainCallbacks()

Callbacks for RunOnMainThread()

Detailed Description

Typedef Documentation

◆ AppEvent_func

◆ AppInit_func

◆ AppIterate_func

◆ AppQuit_func

◆ AppResult

◆ MainThreadCallback

◆ MainThreadCB

Function Documentation

◆ DefaultClassDestroy()

◆ DefaultCreateClass()

◆ DefaultEventClass()

◆ EventClass()

◆ GetAppMetadataProperty()

◆ Init()

◆ InitClass()

◆ InitSubSystem()

◆ IsMainThread()

◆ IterateClass()

◆ Quit()

◆ QuitClass()

◆ QuitSubSystem()

◆ RunOnMainThread() [1/2]

◆ RunOnMainThread() [2/2]

◆ SetAppMetadata()

◆ SetAppMetadataProperty()

◆ WasInit()