sdl3-bindgen-sys
Safe HaskellNone
LanguageGHC2021

SDL3.Sys.Init

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 sDL_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. Initialization flags for init and/or initSubSystem

These are the flags which may be passed to init. You should specify the subsystems which you will be using in your application.

See also
init, quit, initSubSystem, quitSubSystem, wasInit

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.Init.Unsafe); functions curated unsafe-only export only the unsuffixed one. Each alias's documentation records its flavor and rationale.

Full conventions: SDL3.Sys.

Since: 3.2.0

Synopsis

Documentation

module SDL3.Sys.Bindgen.Init

Typed constants

pattern SDL_INIT_AUDIO :: SDL_InitFlags Source #

Typed constant for macro SDL_INIT_AUDIO. Combine with .|. from Data.Bits.

pattern SDL_INIT_VIDEO :: SDL_InitFlags Source #

Typed constant for macro SDL_INIT_VIDEO. Combine with .|. from Data.Bits.

pattern SDL_INIT_JOYSTICK :: SDL_InitFlags Source #

Typed constant for macro SDL_INIT_JOYSTICK. Combine with .|. from Data.Bits.

pattern SDL_INIT_HAPTIC :: SDL_InitFlags Source #

Typed constant for macro SDL_INIT_HAPTIC. Combine with .|. from Data.Bits.

pattern SDL_INIT_GAMEPAD :: SDL_InitFlags Source #

Typed constant for macro SDL_INIT_GAMEPAD. Combine with .|. from Data.Bits.

pattern SDL_INIT_EVENTS :: SDL_InitFlags Source #

Typed constant for macro SDL_INIT_EVENTS. Combine with .|. from Data.Bits.

pattern SDL_INIT_SENSOR :: SDL_InitFlags Source #

Typed constant for macro SDL_INIT_SENSOR. Combine with .|. from Data.Bits.

pattern SDL_INIT_CAMERA :: SDL_InitFlags Source #

Typed constant for macro SDL_INIT_CAMERA. Combine with .|. from Data.Bits.

Function aliases

init Source #

Arguments

:: SDL_InitFlags
flags
subsystem initialization flags.
-> IO Bool 

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: SDL_IOFromFile) and threading (SDL_CreateThread) subsystems are initialized by default. Message boxes (SDL_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 SDL_Log) works without initialization, too.

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

  • sDL_INIT_AUDIO: audio subsystem; automatically initializes the events subsystem
  • sDL_INIT_VIDEO: video subsystem; automatically initializes the events subsystem, should be initialized on the main thread.
  • sDL_INIT_JOYSTICK: joystick subsystem; automatically initializes the events subsystem
  • sDL_INIT_HAPTIC: haptic (force feedback) subsystem
  • sDL_INIT_GAMEPAD: gamepad subsystem; automatically initializes the joystick subsystem
  • sDL_INIT_EVENTS: events subsystem
  • sDL_INIT_SENSOR: sensor subsystem; automatically initializes the events subsystem
  • sDL_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.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
setAppMetadata, setAppMetadataProperty, initSubSystem, quit, setMainReady, wasInit

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_Init. The safe flavor is initSafe : driver loading can take hundreds of milliseconds.
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_Init, defined at SDL3/SDL_init.h 238:34

Since: 3.2.0

initSafe Source #

Arguments

:: SDL_InitFlags
flags
subsystem initialization flags.
-> IO Bool 

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: SDL_IOFromFile) and threading (SDL_CreateThread) subsystems are initialized by default. Message boxes (SDL_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 SDL_Log) works without initialization, too.

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

  • sDL_INIT_AUDIO: audio subsystem; automatically initializes the events subsystem
  • sDL_INIT_VIDEO: video subsystem; automatically initializes the events subsystem, should be initialized on the main thread.
  • sDL_INIT_JOYSTICK: joystick subsystem; automatically initializes the events subsystem
  • sDL_INIT_HAPTIC: haptic (force feedback) subsystem
  • sDL_INIT_GAMEPAD: gamepad subsystem; automatically initializes the joystick subsystem
  • sDL_INIT_EVENTS: events subsystem
  • sDL_INIT_SENSOR: sensor subsystem; automatically initializes the events subsystem
  • sDL_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.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
setAppMetadata, setAppMetadataProperty, initSubSystem, quit, setMainReady, wasInit

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_Init. The unsafe flavor is init : driver loading can take hundreds of milliseconds.
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_Init, defined at SDL3/SDL_init.h 238:34

Since: 3.2.0

initSubSystem Source #

Arguments

:: SDL_InitFlags
flags
any of the flags used by init; see init for details.
-> IO Bool 

Compatibility function to initialize the SDL library.

This function and init are interchangeable.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
init, quit, quitSubSystem

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_InitSubSystem. The safe flavor is initSubSystemSafe : driver loading can take hundreds of milliseconds.
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_InitSubSystem, defined at SDL3/SDL_init.h 257:34

Since: 3.2.0

initSubSystemSafe Source #

Arguments

:: SDL_InitFlags
flags
any of the flags used by init; see init for details.
-> IO Bool 

Compatibility function to initialize the SDL library.

This function and init are interchangeable.

Returns
true on success or false on failure; call getError for more information.
Thread safety
This function should only be called on the main thread.
See also
init, quit, quitSubSystem

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_InitSubSystem. The unsafe flavor is initSubSystem : driver loading can take hundreds of milliseconds.
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_InitSubSystem, defined at SDL3/SDL_init.h 257:34

Since: 3.2.0

quitSubSystem Source #

Arguments

:: SDL_InitFlags
flags
any of the flags used by init; see init for details.
-> IO () 

Shut down specific SDL subsystems.

You still need to call quit even if you close all open subsystems with quitSubSystem.

Thread safety
This function is not thread safe.
See also
initSubSystem, quit

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_QuitSubSystem. The safe flavor is quitSubSystemSafe : video quit invokes the clipboard cleanup callback synchronously.
C declaration
SDL_QuitSubSystem, defined at SDL3/SDL_init.h 274:34

Since: 3.2.0

quitSubSystemSafe Source #

Arguments

:: SDL_InitFlags
flags
any of the flags used by init; see init for details.
-> IO () 

Shut down specific SDL subsystems.

You still need to call quit even if you close all open subsystems with quitSubSystem.

Thread safety
This function is not thread safe.
See also
initSubSystem, quit

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_QuitSubSystem. The unsafe flavor is quitSubSystem : video quit invokes the clipboard cleanup callback synchronously.
C declaration
SDL_QuitSubSystem, defined at SDL3/SDL_init.h 274:34

Since: 3.2.0

wasInit Source #

Arguments

:: SDL_InitFlags
flags
any of the flags used by init; see init for details.
-> IO SDL_InitFlags 

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

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.
See also
init, initSubSystem

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_WasInit. The safe flavor is wasInitSafe .
C declaration
SDL_WasInit, defined at SDL3/SDL_init.h 290:43

Since: 3.2.0

wasInitSafe Source #

Arguments

:: SDL_InitFlags
flags
any of the flags used by init; see init for details.
-> IO SDL_InitFlags 

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

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.
See also
init, initSubSystem

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_WasInit. The unsafe flavor is wasInit .
C declaration
SDL_WasInit, defined at SDL3/SDL_init.h 290:43

Since: 3.2.0

quit :: IO () Source #

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.
See also
init, quitSubSystem

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_Quit. The safe flavor is quitSafe : video quit invokes the clipboard cleanup callback synchronously.
C declaration
SDL_Quit, defined at SDL3/SDL_init.h 310:34

Since: 3.2.0

quitSafe :: IO () Source #

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.
See also
init, quitSubSystem

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_Quit. The unsafe flavor is quit : video quit invokes the clipboard cleanup callback synchronously.
C declaration
SDL_Quit, defined at SDL3/SDL_init.h 310:34

Since: 3.2.0

isMainThread :: IO Bool Source #

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 SDL_Init(SDL_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.
See also
runOnMainThreadSafe

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_IsMainThread. The safe flavor is isMainThreadSafe .
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_IsMainThread, defined at SDL3/SDL_init.h 330:34

Since: 3.2.0

isMainThreadSafe :: IO Bool Source #

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 SDL_Init(SDL_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.
See also
runOnMainThreadSafe

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_IsMainThread. The unsafe flavor is isMainThread .
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_IsMainThread, defined at SDL3/SDL_init.h 330:34

Since: 3.2.0

runOnMainThreadSafe Source #

Arguments

:: SDL_MainThreadCallback
callback
the callback to call on the main thread.
-> Ptr Void
userdata
a pointer that is passed to callback.
-> Bool
wait_complete
true to wait for the callback to complete, false to return immediately.
-> IO Bool 

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.

Returns
true on success or false on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
isMainThread

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_RunOnMainThread. The unsafe import is not exported : invokes synchronously on the main thread, or blocks until the main thread runs it. 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.Init.Unsafe.sDL_RunOnMainThread.
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_RunOnMainThread, defined at SDL3/SDL_init.h 367:34

Since: 3.2.0

setAppMetadata Source #

Arguments

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

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 NULL, 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 NULL removes any previous metadata.

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

Returns
true on success or false on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
setAppMetadataProperty

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_SetAppMetadata. The safe flavor is setAppMetadataSafe .
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_SetAppMetadata, defined at SDL3/SDL_init.h 405:34

Since: 3.2.0

setAppMetadataSafe Source #

Arguments

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

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 NULL, 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 NULL removes any previous metadata.

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

Returns
true on success or false on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
setAppMetadataProperty

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_SetAppMetadata. The unsafe flavor is setAppMetadata .
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_SetAppMetadata, defined at SDL3/SDL_init.h 405:34

Since: 3.2.0

setAppMetadataProperty Source #

Arguments

:: PtrConst CChar
name
the name of the metadata property to set.
-> PtrConst CChar
value
the value of the property, or NULL to remove that property.
-> IO Bool 

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:

  • sDL_PROP_APP_METADATA_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. If not provided by the app, SDL will attempt to pick a reasonable default (the app's binary's name if the platform can provide it, or "SDL Application" if all else fails).
  • sDL_PROP_APP_METADATA_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.
  • sDL_PROP_APP_METADATA_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.
  • sDL_PROP_APP_METADATA_CREATOR_STRING: The human-readable name of the creator/developer/maker of this app, like "MojoWorkshop, LLC"
  • sDL_PROP_APP_METADATA_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.
  • sDL_PROP_APP_METADATA_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.
  • sDL_PROP_APP_METADATA_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".
Returns
true on success or false on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
getAppMetadataProperty, setAppMetadata

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_SetAppMetadataProperty. The safe flavor is setAppMetadataPropertySafe .
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_SetAppMetadataProperty, defined at SDL3/SDL_init.h 469:34

Since: 3.2.0

setAppMetadataPropertySafe Source #

Arguments

:: PtrConst CChar
name
the name of the metadata property to set.
-> PtrConst CChar
value
the value of the property, or NULL to remove that property.
-> IO Bool 

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:

  • sDL_PROP_APP_METADATA_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. If not provided by the app, SDL will attempt to pick a reasonable default (the app's binary's name if the platform can provide it, or "SDL Application" if all else fails).
  • sDL_PROP_APP_METADATA_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.
  • sDL_PROP_APP_METADATA_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.
  • sDL_PROP_APP_METADATA_CREATOR_STRING: The human-readable name of the creator/developer/maker of this app, like "MojoWorkshop, LLC"
  • sDL_PROP_APP_METADATA_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.
  • sDL_PROP_APP_METADATA_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.
  • sDL_PROP_APP_METADATA_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".
Returns
true on success or false on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
getAppMetadataProperty, setAppMetadata

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_SetAppMetadataProperty. The unsafe flavor is setAppMetadataProperty .
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_SetAppMetadataProperty, defined at SDL3/SDL_init.h 469:34

Since: 3.2.0

getAppMetadataProperty Source #

Arguments

:: PtrConst CChar
name
the name of the metadata property to get.
-> IO (PtrConst CChar) 

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.

Returns
the current value of the metadata property, or the default if it is not set, NULL 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.
See also
setAppMetadata, setAppMetadataProperty

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_GetAppMetadataProperty. The safe flavor is getAppMetadataPropertySafe .
C declaration
SDL_GetAppMetadataProperty, defined at SDL3/SDL_init.h 500:42

Since: 3.2.0

getAppMetadataPropertySafe Source #

Arguments

:: PtrConst CChar
name
the name of the metadata property to get.
-> IO (PtrConst CChar) 

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.

Returns
the current value of the metadata property, or the default if it is not set, NULL 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.
See also
setAppMetadata, setAppMetadataProperty

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_GetAppMetadataProperty. The unsafe flavor is getAppMetadataProperty .
C declaration
SDL_GetAppMetadataProperty, defined at SDL3/SDL_init.h 500:42

Since: 3.2.0