SDL_properties.h File Reference
`#include <SDL3/SDL_stdinc.h>`
`#include <SDL3/SDL_error.h>`
`#include <SDL3/SDL_begin_code.h>`
`#include <SDL3/SDL_close_code.h>`
Include dependency graph for SDL_properties.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Macros

#define | SDL_PROP_NAME_STRING "SDL.name"

## Typedefs

typedef Uint32 | SDL_PropertiesID
typedef void(* | SDL_CleanupPropertyCallback) (void *userdata, void *value)
typedef void(* | SDL_EnumeratePropertiesCallback) (void *userdata, SDL_PropertiesID props, const char *name)

## Enumerations

enum | SDL_PropertyType { SDL_PROPERTY_TYPE_INVALID , SDL_PROPERTY_TYPE_POINTER , SDL_PROPERTY_TYPE_STRING , SDL_PROPERTY_TYPE_NUMBER , SDL_PROPERTY_TYPE_FLOAT , SDL_PROPERTY_TYPE_BOOLEAN }

## Functions

SDL_PropertiesID | SDL_GetGlobalProperties (void)
SDL_PropertiesID | SDL_CreateProperties (void)
bool | SDL_CopyProperties (SDL_PropertiesID src, SDL_PropertiesID dst)
bool | SDL_LockProperties (SDL_PropertiesID props)
void | SDL_UnlockProperties (SDL_PropertiesID props)
bool | SDL_SetPointerPropertyWithCleanup (SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata)
bool | SDL_SetPointerProperty (SDL_PropertiesID props, const char *name, void *value)
bool | SDL_SetStringProperty (SDL_PropertiesID props, const char *name, const char *value)
bool | SDL_SetNumberProperty (SDL_PropertiesID props, const char *name, Sint64 value)
bool | SDL_SetFloatProperty (SDL_PropertiesID props, const char *name, float value)
bool | SDL_SetBooleanProperty (SDL_PropertiesID props, const char *name, bool value)
bool | SDL_HasProperty (SDL_PropertiesID props, const char *name)
SDL_PropertyType | SDL_GetPropertyType (SDL_PropertiesID props, const char *name)
void * | SDL_GetPointerProperty (SDL_PropertiesID props, const char *name, void *default_value)
const char * | SDL_GetStringProperty (SDL_PropertiesID props, const char *name, const char *default_value)
Sint64 | SDL_GetNumberProperty (SDL_PropertiesID props, const char *name, Sint64 default_value)
float | SDL_GetFloatProperty (SDL_PropertiesID props, const char *name, float default_value)
bool | SDL_GetBooleanProperty (SDL_PropertiesID props, const char *name, bool default_value)
bool | SDL_ClearProperty (SDL_PropertiesID props, const char *name)
bool | SDL_EnumerateProperties (SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata)
void | SDL_DestroyProperties (SDL_PropertiesID props)

## Macro Definition Documentation

## SDL_PROP_NAME_STRING

#define SDL_PROP_NAME_STRING "SDL.name"

A generic property for naming things.

This property is intended to be added to any SDL_PropertiesID that needs a generic name associated with the property set. It is not guaranteed that any property set will include this key, but it is convenient to have a standard key that any piece of code could reasonably agree to use.

For example, the properties associated with an SDL_Texture might have a name string of "player sprites", or an SDL_AudioStream might have "background music", etc. This might also be useful for an SDL_IOStream to list the path to its asset.

There is no format for the value set with this key; it is expected to be human-readable and informational in nature, possibly for logging or debugging purposes.

SDL does not currently set this property on any objects it creates, but this may change in later versions; it is currently expected that apps and external libraries will take advantage of it, when appropriate.

Since
  This macro is available since SDL 3.4.0.

Definition at line 106 of file SDL_properties.h.

## Typedef Documentation

## SDL_CleanupPropertyCallback

typedef void(* SDL_CleanupPropertyCallback) (void *userdata, void *value)

A callback used to free resources when a property is deleted.

This should release any resources associated with value that are no longer needed.

This callback is set per-property. Different properties in the same group can have different cleanup callbacks.

This callback will be called during SDL_SetPointerPropertyWithCleanup if the function fails for any reason.

Parameters

  userdata | an app-defined pointer passed to the callback.
  value | the pointer assigned to the property to clean up.

\threadsafety This callback may fire without any locks held; if this is a concern, the app should provide its own locking.

Since
  This datatype is available since SDL 3.2.0.

See also
  SDL_SetPointerPropertyWithCleanup

Definition at line 216 of file SDL_properties.h.

## SDL_EnumeratePropertiesCallback

typedef void(* SDL_EnumeratePropertiesCallback) (void *userdata, SDL_PropertiesID props, const char *name)

A callback used to enumerate all the properties in a group of properties.

This callback is called from SDL_EnumerateProperties(), and is called once per property in the set.

Parameters

  userdata | an app-defined pointer passed to the callback.
  props | the SDL_PropertiesID that is being enumerated.
  name | the next property name in the enumeration.

\threadsafety SDL_EnumerateProperties holds a lock on props during this callback.

Since
  This datatype is available since SDL 3.2.0.

See also
  SDL_EnumerateProperties

Definition at line 528 of file SDL_properties.h.

## SDL_PropertiesID

typedef Uint32 SDL_PropertiesID

# CategoryProperties

A property is a variable that can be created and retrieved by name at runtime.

All properties are part of a property group (SDL_PropertiesID). A property group can be created with the SDL_CreateProperties function and destroyed with the SDL_DestroyProperties function.

Properties can be added to and retrieved from a property group through the following functions:

- SDL_SetPointerProperty and SDL_GetPointerProperty operate on void* pointer types.
- SDL_SetStringProperty and SDL_GetStringProperty operate on string types.
- SDL_SetNumberProperty and SDL_GetNumberProperty operate on signed 64-bit integer types.
- SDL_SetFloatProperty and SDL_GetFloatProperty operate on floating point types.
- SDL_SetBooleanProperty and SDL_GetBooleanProperty operate on boolean types.

Properties can be removed from a group by using SDL_ClearProperty. An ID that represents a properties set.

Since
  This datatype is available since SDL 3.2.0.

Definition at line 66 of file SDL_properties.h.

## Enumeration Type Documentation

## SDL_PropertyType

enum SDL_PropertyType

SDL property type

Since
  This enum is available since SDL 3.2.0.

Enumerator
SDL_PROPERTY_TYPE_INVALID |
SDL_PROPERTY_TYPE_POINTER |
SDL_PROPERTY_TYPE_STRING |
SDL_PROPERTY_TYPE_NUMBER |
SDL_PROPERTY_TYPE_FLOAT |
SDL_PROPERTY_TYPE_BOOLEAN |

Definition at line 73 of file SDL_properties.h.

{
SDL_PROPERTY_TYPE_INVALID,
SDL_PROPERTY_TYPE_POINTER,
SDL_PROPERTY_TYPE_STRING,
SDL_PROPERTY_TYPE_NUMBER,
SDL_PROPERTY_TYPE_FLOAT,
SDL_PROPERTY_TYPE_BOOLEAN
} SDL_PropertyType;
SDL_PropertyType
SDL_PropertyType
Definition SDL_properties.h:74
SDL_PROPERTY_TYPE_NUMBER
@ SDL_PROPERTY_TYPE_NUMBER
Definition SDL_properties.h:78
SDL_PROPERTY_TYPE_FLOAT
@ SDL_PROPERTY_TYPE_FLOAT
Definition SDL_properties.h:79
SDL_PROPERTY_TYPE_BOOLEAN
@ SDL_PROPERTY_TYPE_BOOLEAN
Definition SDL_properties.h:80
SDL_PROPERTY_TYPE_INVALID
@ SDL_PROPERTY_TYPE_INVALID
Definition SDL_properties.h:75
SDL_PROPERTY_TYPE_POINTER
@ SDL_PROPERTY_TYPE_POINTER
Definition SDL_properties.h:76
SDL_PROPERTY_TYPE_STRING
@ SDL_PROPERTY_TYPE_STRING
Definition SDL_properties.h:77

## Function Documentation

## SDL_ClearProperty()

bool SDL_ClearProperty | ( | SDL_PropertiesID | props,
|  | const char * | name )

extern

Clear a property from a group of properties.

Parameters

  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.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

## SDL_CopyProperties()

bool SDL_CopyProperties | ( | SDL_PropertiesID | src,
|  | SDL_PropertiesID | dst )

extern

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.

Parameters

  src | the properties to copy.
  dst | the destination properties.

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

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

Since
  This function is available since SDL 3.2.0.

## SDL_CreateProperties()

SDL_PropertiesID SDL_CreateProperties | ( | void |  | ) |

extern

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.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_DestroyProperties

## SDL_DestroyProperties()

void SDL_DestroyProperties | ( | SDL_PropertiesID | props | ) |

extern

Destroy a group of properties.

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

Parameters

  props | the properties to destroy.

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

Since
  This function is available since SDL 3.2.0.

See also
  SDL_CreateProperties

## SDL_EnumerateProperties()

bool SDL_EnumerateProperties | ( | SDL_PropertiesID | props,
|  | SDL_EnumeratePropertiesCallback | callback,
|  | void * | userdata )

extern

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.

Parameters

  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.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

## SDL_GetBooleanProperty()

bool SDL_GetBooleanProperty | ( | SDL_PropertiesID | props,
|  | const char * | name,
|  | bool | default_value )

extern

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.

Parameters

  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.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetPropertyType
  SDL_HasProperty
  SDL_SetBooleanProperty

## SDL_GetFloatProperty()

float SDL_GetFloatProperty | ( | SDL_PropertiesID | props,
|  | const char * | name,
|  | float | default_value )

extern

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.

Parameters

  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.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetPropertyType
  SDL_HasProperty
  SDL_SetFloatProperty

## SDL_GetGlobalProperties()

SDL_PropertiesID SDL_GetGlobalProperties | ( | void |  | ) |

extern

Get the global SDL properties.

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

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

## SDL_GetNumberProperty()

Sint64 SDL_GetNumberProperty | ( | SDL_PropertiesID | props,
|  | const char * | name,
|  | Sint64 | default_value )

extern

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.

Parameters

  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.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetPropertyType
  SDL_HasProperty
  SDL_SetNumberProperty

## SDL_GetPointerProperty()

void * SDL_GetPointerProperty | ( | SDL_PropertiesID | props,
|  | const char * | name,
|  | void * | default_value )

extern

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.

Parameters

  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.

\threadsafety 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().

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetBooleanProperty
  SDL_GetFloatProperty
  SDL_GetNumberProperty
  SDL_GetPropertyType
  SDL_GetStringProperty
  SDL_HasProperty
  SDL_SetPointerProperty

## SDL_GetPropertyType()

SDL_PropertyType SDL_GetPropertyType | ( | SDL_PropertiesID | props,
|  | const char * | name )

extern

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

Parameters

  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.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_HasProperty

## SDL_GetStringProperty()

const char * SDL_GetStringProperty | ( | SDL_PropertiesID | props,
|  | const char * | name,
|  | const char * | default_value )

extern

Get a string property from a group of properties.

Parameters

  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.

\threadsafety 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().

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetPropertyType
  SDL_HasProperty
  SDL_SetStringProperty

## SDL_HasProperty()

bool SDL_HasProperty | ( | SDL_PropertiesID | props,
|  | const char * | name )

extern

Return whether a property exists in a group of properties.

Parameters

  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.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetPropertyType

## SDL_LockProperties()

bool SDL_LockProperties | ( | SDL_PropertiesID | props | ) |

extern

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.

Parameters

  props | the properties to lock.

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

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_UnlockProperties

## SDL_SetBooleanProperty()

bool SDL_SetBooleanProperty | ( | SDL_PropertiesID | props,
|  | const char * | name,
|  | bool | value )

extern

Set a boolean property in a group of properties.

Parameters

  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.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetBooleanProperty

## SDL_SetFloatProperty()

bool SDL_SetFloatProperty | ( | SDL_PropertiesID | props,
|  | const char * | name,
|  | float | value )

extern

Set a floating point property in a group of properties.

Parameters

  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.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetFloatProperty

## SDL_SetNumberProperty()

bool SDL_SetNumberProperty | ( | SDL_PropertiesID | props,
|  | const char * | name,
|  | Sint64 | value )

extern

Set an integer property in a group of properties.

Parameters

  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.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetNumberProperty

## SDL_SetPointerProperty()

bool SDL_SetPointerProperty | ( | SDL_PropertiesID | props,
|  | const char * | name,
|  | void * | value )

extern

Set a pointer property in a group of properties.

Parameters

  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.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetPointerProperty
  SDL_HasProperty
  SDL_SetBooleanProperty
  SDL_SetFloatProperty
  SDL_SetNumberProperty
  SDL_SetPointerPropertyWithCleanup
  SDL_SetStringProperty

## SDL_SetPointerPropertyWithCleanup()

bool SDL_SetPointerPropertyWithCleanup | ( | SDL_PropertiesID | props,
|  | const char * | name,
|  | void * | value,
|  | SDL_CleanupPropertyCallback | cleanup,
|  | void * | userdata )

extern

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.

Parameters

  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.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetPointerProperty
  SDL_SetPointerProperty
  SDL_CleanupPropertyCallback

## SDL_SetStringProperty()

bool SDL_SetStringProperty | ( | SDL_PropertiesID | props,
|  | const char * | name,
|  | const char * | value )

extern

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.

Parameters

  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.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_GetStringProperty

## SDL_UnlockProperties()

void SDL_UnlockProperties | ( | SDL_PropertiesID | props | ) |

extern

Unlock a group of properties.

Parameters

  props | the properties to unlock.

\threadsafety It is safe to call this function from any thread.

Since
  This function is available since SDL 3.2.0.

See also
  SDL_LockProperties