sdl3-bindgen-sys
Safe HaskellNone
LanguageGHC2021

SDL3.Sys.Main

Description

App entry-point handling; SDL_main is not bound here.

FFI conventions

Unsuffixed aliases are unsafe foreign imports; aliases suffixed Safe are safe. Functions whose callbacks fire during the call export only the Safe alias (the genuine unsafe import stays reachable under SDL3.Sys.Bindgen.Main.Unsafe); functions curated unsafe-only export only the unsuffixed one. Each alias's documentation records its flavor and rationale.

Full conventions: SDL3.Sys.

Synopsis

Documentation

module SDL3.Sys.Bindgen.Main

Function aliases

setMainReady :: IO () Source #

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 SDL_MAIN_HANDLED before including SDL.h.

Thread safety
This function is not thread safe.
See also
init

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_SetMainReady. The safe flavor is setMainReadySafe .
C declaration
SDL_SetMainReady, defined at SDL3/SDL_main.h 549:34

Since: 3.2.0

setMainReadySafe :: IO () Source #

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 SDL_MAIN_HANDLED before including SDL.h.

Thread safety
This function is not thread safe.
See also
init

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_SetMainReady. The unsafe flavor is setMainReady .
C declaration
SDL_SetMainReady, defined at SDL3/SDL_main.h 549:34

Since: 3.2.0

runAppSafe Source #

Arguments

:: Int32
argc
the argc parameter from the application's main() function, or 0 if the platform's main-equivalent has no argc.
-> Ptr (Elem (IncompleteArray (Ptr CChar)))
argv
the argv parameter from the application's main() function, or NULL if the platform's main-equivalent has no argv.
-> SDL_main_func
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.
-> Ptr Void
reserved
should be NULL (reserved for future use, will probably be platform-specific then).
-> IO Int32 

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

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

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.

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_RunApp. The unsafe import is not exported : runs the provided main function synchronously. If your callback is a non-Haskell function pointer that never re-enters the Haskell runtime, the unsafe import remains available as SDL3.Sys.Bindgen.Main.Unsafe.sDL_RunApp.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_RunApp, defined at SDL3/SDL_main.h 582:33

Since: 3.2.0

enterAppMainCallbacksSafe Source #

Arguments

:: Int32
argc
standard Unix main argc.
-> Ptr (Elem (IncompleteArray (Ptr CChar)))
argv
standard Unix main argv.
-> SDL_AppInit_func
appinit
the application's SDL_AppInit function.
-> SDL_AppIterate_func
appiter
the application's SDL_AppIterate function.
-> SDL_AppEvent_func
appevent
the application's SDL_AppEvent function.
-> SDL_AppQuit_func
appquit
the application's SDL_AppQuit function.
-> IO Int32 

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.

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.

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_EnterAppMainCallbacks. The unsafe import is not exported : runs the whole app main loop through the callbacks synchronously. If your callback is a non-Haskell function pointer that never re-enters the Haskell runtime, the unsafe import remains available as SDL3.Sys.Bindgen.Main.Unsafe.sDL_EnterAppMainCallbacks.
Scalars
The binding generation has mapped C scalars to native Haskell scalars for this function. Pointers and structs are untouched by this best-effort mapping. Higher-level bindings are expected to map structs and pointers as appropriate.
C declaration
SDL_EnterAppMainCallbacks, defined at SDL3/SDL_main.h 609:33

Since: 3.2.0

gdkSuspendComplete :: IO () Source #

Callback from the application to let the suspend continue.

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

When using SDL_Render, your event watch should be added after creating the SDL_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 SDL_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.
See also
addEventWatch

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GDKSuspendComplete. The safe flavor is gdkSuspendCompleteSafe .
C declaration
SDL_GDKSuspendComplete, defined at SDL3/SDL_main.h 688:34

Since: 3.2.0

gdkSuspendCompleteSafe :: IO () Source #

Callback from the application to let the suspend continue.

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

When using SDL_Render, your event watch should be added after creating the SDL_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 SDL_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.
See also
addEventWatch

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GDKSuspendComplete. The unsafe flavor is gdkSuspendComplete .
C declaration
SDL_GDKSuspendComplete, defined at SDL3/SDL_main.h 688:34

Since: 3.2.0