Documentation

Get the global SDL properties.

Returns

a valid property ID on success or 0 on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_GetGlobalProperties, defined at SDL3/SDL_properties.h 118:46

Since: 3.2.0

Create a group of properties.

All properties are automatically destroyed when SDL_Quit() is called.

Returns

an ID for a new group of properties, or 0 on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_DestroyProperties

C declaration

SDL_CreateProperties, defined at SDL3/SDL_properties.h 134:46

Since: 3.2.0

Copy a group of properties.

Copy all the properties from one group of properties to another, with the exception of properties requiring cleanup (set using SDL_SetPointerPropertyWithCleanup()), which will not be copied. Any property that already exists on dst will be overwritten.

src

the properties to copy.

dst

the destination properties.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread. This function acquires simultaneous mutex locks on both the source and destination property sets.

C declaration

SDL_CopyProperties, defined at SDL3/SDL_properties.h 155:34

Since: 3.2.0

Lock a group of properties.

Obtain a multi-threaded lock for these properties. Other threads will wait while trying to lock these properties until they are unlocked. Properties must be unlocked before they are destroyed.

The lock is automatically taken when setting individual properties, this function is only needed when you want to set several properties atomically or want to guarantee that properties being queried aren't freed in another thread.

props

the properties to lock.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_UnlockProperties

C declaration

SDL_LockProperties, defined at SDL3/SDL_properties.h 179:34

Since: 3.2.0

Unlock a group of properties.

props

the properties to unlock.

Thread safety

It is safe to call this function from any thread.

See also

sDL_LockProperties

C declaration

SDL_UnlockProperties, defined at SDL3/SDL_properties.h 192:34

Since: 3.2.0

Set a pointer property in a group of properties with a cleanup function that is called when the property is deleted.

The cleanup function is also called if setting the property fails for any reason.

For simply setting basic data types, like numbers, bools, or strings, use SDL_SetNumberProperty, SDL_SetBooleanProperty, or SDL_SetStringProperty instead, as those functions will handle cleanup on your behalf. This function is only for more complex, custom data.

props

the properties to modify.

name

the name of the property to modify.

value

the new value of the property, or NULL to delete the property.

cleanup

the function to call when this property is deleted, or NULL if no cleanup is necessary.

userdata

a pointer that is passed to the cleanup function.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetPointerProperty, sDL_SetPointerProperty, SDL_CleanupPropertyCallback

C declaration

SDL_SetPointerPropertyWithCleanup, defined at SDL3/SDL_properties.h 247:34

Since: 3.2.0

Set a pointer property in a group of properties.

props

the properties to modify.

name

the name of the property to modify.

value

the new value of the property, or NULL to delete the property.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetPointerProperty, sDL_HasProperty, sDL_SetBooleanProperty, sDL_SetFloatProperty, sDL_SetNumberProperty, sDL_SetPointerPropertyWithCleanup, sDL_SetStringProperty

C declaration

SDL_SetPointerProperty, defined at SDL3/SDL_properties.h 270:34

Since: 3.2.0

Set a string property in a group of properties.

This function makes a copy of the string; the caller does not have to preserve the data after this call completes.

props

the properties to modify.

name

the name of the property to modify.

value

the new value of the property, or NULL to delete the property.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetStringProperty

C declaration

SDL_SetStringProperty, defined at SDL3/SDL_properties.h 290:34

Since: 3.2.0

Set an integer property in a group of properties.

props

the properties to modify.

name

the name of the property to modify.

value

the new value of the property.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetNumberProperty

C declaration

SDL_SetNumberProperty, defined at SDL3/SDL_properties.h 307:34

Since: 3.2.0

Set a floating point property in a group of properties.

props

the properties to modify.

name

the name of the property to modify.

value

the new value of the property.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetFloatProperty

C declaration

SDL_SetFloatProperty, defined at SDL3/SDL_properties.h 324:34

Since: 3.2.0

Set a boolean property in a group of properties.

props

the properties to modify.

name

the name of the property to modify.

value

the new value of the property.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetBooleanProperty

C declaration

SDL_SetBooleanProperty, defined at SDL3/SDL_properties.h 341:34

Since: 3.2.0

Return whether a property exists in a group of properties.

props

the properties to query.

name

the name of the property to query.

Returns

true if the property exists, or false if it doesn't.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetPropertyType

C declaration

SDL_HasProperty, defined at SDL3/SDL_properties.h 356:34

Since: 3.2.0

Get the type of a property in a group of properties.

props

the properties to query.

name

the name of the property to query.

Returns

the type of the property, or SDL_PROPERTY_TYPE_INVALID if it is not set.

Thread safety

It is safe to call this function from any thread.

See also

sDL_HasProperty

C declaration

SDL_GetPropertyType, defined at SDL3/SDL_properties.h 372:46

Since: 3.2.0

Get a pointer property from a group of properties.

By convention, the names of properties that SDL exposes on objects will start with "SDL.", and properties that SDL uses internally will start with "SDL.internal.". These should be considered read-only and should not be modified by applications.

props

the properties to query.

name

the name of the property to query.

default_value

the default value of the property.

Returns

the value of the property, or default_value if it is not set or not a pointer property.

Thread safety

It is safe to call this function from any thread, although the data returned is not protected and could potentially be freed if you call SDL_SetPointerProperty() or SDL_ClearProperty() on these properties from another thread. If you need to avoid this, use SDL_LockProperties() and SDL_UnlockProperties().

See also

sDL_GetBooleanProperty, sDL_GetFloatProperty, sDL_GetNumberProperty, sDL_GetPropertyType, sDL_GetStringProperty, sDL_HasProperty, sDL_SetPointerProperty

C declaration

SDL_GetPointerProperty, defined at SDL3/SDL_properties.h 405:36

Since: 3.2.0

Get a string property from a group of properties.

props

the properties to query.

name

the name of the property to query.

default_value

the default value of the property.

Returns

the value of the property, or default_value if it is not set or not a string property.

Thread safety

It is safe to call this function from any thread, although the data returned is not protected and could potentially be freed if you call SDL_SetStringProperty() or SDL_ClearProperty() on these properties from another thread. If you need to avoid this, use SDL_LockProperties() and SDL_UnlockProperties().

See also

sDL_GetPropertyType, sDL_HasProperty, sDL_SetStringProperty

C declaration

SDL_GetStringProperty, defined at SDL3/SDL_properties.h 429:42

Since: 3.2.0

Get a number property from a group of properties.

You can use SDL_GetPropertyType() to query whether the property exists and is a number property.

props

the properties to query.

name

the name of the property to query.

default_value

the default value of the property.

Returns

the value of the property, or default_value if it is not set or not a number property.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetPropertyType, sDL_HasProperty, sDL_SetNumberProperty

C declaration

SDL_GetNumberProperty, defined at SDL3/SDL_properties.h 451:36

Since: 3.2.0

Get a floating point property from a group of properties.

You can use SDL_GetPropertyType() to query whether the property exists and is a floating point property.

props

the properties to query.

name

the name of the property to query.

default_value

the default value of the property.

Returns

the value of the property, or default_value if it is not set or not a float property.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetPropertyType, sDL_HasProperty, sDL_SetFloatProperty

C declaration

SDL_GetFloatProperty, defined at SDL3/SDL_properties.h 473:35

Since: 3.2.0

Get a boolean property from a group of properties.

You can use SDL_GetPropertyType() to query whether the property exists and is a boolean property.

props

the properties to query.

name

the name of the property to query.

default_value

the default value of the property.

Returns

the value of the property, or default_value if it is not set or not a boolean property.

Thread safety

It is safe to call this function from any thread.

See also

sDL_GetPropertyType, sDL_HasProperty, sDL_SetBooleanProperty

C declaration

SDL_GetBooleanProperty, defined at SDL3/SDL_properties.h 495:34

Since: 3.2.0

Clear a property from a group of properties.

props

the properties to modify.

name

the name of the property to clear.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_ClearProperty, defined at SDL3/SDL_properties.h 509:34

Since: 3.2.0

Enumerate the properties contained in a group of properties.

The callback function is called for each property in the group of properties. The properties are locked during enumeration.

props

the properties to query.

callback

the function to call for each property.

userdata

a pointer that is passed to callback.

Returns

true on success or false on failure; call SDL_GetError() for more information.

Thread safety

It is safe to call this function from any thread.

C declaration

SDL_EnumerateProperties, defined at SDL3/SDL_properties.h 546:34

Since: 3.2.0

Destroy a group of properties.

All properties are deleted and their cleanup functions will be called, if any.

props

the properties to destroy.

Thread safety

This function should not be called while these properties are locked or other threads might be setting or getting values from these properties.

See also

sDL_CreateProperties

C declaration

SDL_DestroyProperties, defined at SDL3/SDL_properties.h 564:34

Since: 3.2.0