SDL 3.0
SDL_properties.h File Reference
+ 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.

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)
 

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
userdataan app-defined pointer passed to the callback.
valuethe 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 187 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
userdataan app-defined pointer passed to the callback.
propsthe SDL_PropertiesID that is being enumerated.
namethe 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 499 of file SDL_properties.h.

◆ 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. SDL properties ID

Since
This datatype is available since SDL 3.2.0.

Definition at line 66 of file SDL_properties.h.

Enumeration Type Documentation

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

74{
SDL_PropertyType
@ SDL_PROPERTY_TYPE_NUMBER
@ SDL_PROPERTY_TYPE_FLOAT
@ SDL_PROPERTY_TYPE_BOOLEAN
@ SDL_PROPERTY_TYPE_INVALID
@ SDL_PROPERTY_TYPE_POINTER
@ SDL_PROPERTY_TYPE_STRING

Function Documentation

◆ SDL_ClearProperty()

bool SDL_ClearProperty ( SDL_PropertiesID  props,
const char *  name 
)

Clear a property from a group of properties.

Parameters
propsthe properties to modify.
namethe 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 
)

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
srcthe properties to copy.
dstthe 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.

Since
This function is available since SDL 3.2.0.

◆ SDL_CreateProperties()

SDL_PropertiesID SDL_CreateProperties ( void  )

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)

Destroy a group of properties.

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

Parameters
propsthe 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 
)

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
propsthe properties to query.
callbackthe function to call for each property.
userdataa 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 
)

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
propsthe properties to query.
namethe name of the property to query.
default_valuethe 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 
)

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
propsthe properties to query.
namethe name of the property to query.
default_valuethe 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  )

Get the global SDL properties.

Returns
a valid property ID on success or 0 on failure; call SDL_GetError() for more information.
Since
This function is available since SDL 3.2.0.

◆ SDL_GetNumberProperty()

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

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
propsthe properties to query.
namethe name of the property to query.
default_valuethe 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 
)

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
propsthe properties to query.
namethe name of the property to query.
default_valuethe 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 
)

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

Parameters
propsthe properties to query.
namethe 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 
)

Get a string property from a group of properties.

Parameters
propsthe properties to query.
namethe name of the property to query.
default_valuethe 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 
)

Return whether a property exists in a group of properties.

Parameters
propsthe properties to query.
namethe 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)

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
propsthe 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 
)

Set a boolean property in a group of properties.

Parameters
propsthe properties to modify.
namethe name of the property to modify.
valuethe 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 
)

Set a floating point property in a group of properties.

Parameters
propsthe properties to modify.
namethe name of the property to modify.
valuethe 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 
)

Set an integer property in a group of properties.

Parameters
propsthe properties to modify.
namethe name of the property to modify.
valuethe 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 
)

Set a pointer property in a group of properties.

Parameters
propsthe properties to modify.
namethe name of the property to modify.
valuethe 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 
)

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
propsthe properties to modify.
namethe name of the property to modify.
valuethe new value of the property, or NULL to delete the property.
cleanupthe function to call when this property is deleted, or NULL if no cleanup is necessary.
userdataa 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 
)

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
propsthe properties to modify.
namethe name of the property to modify.
valuethe 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)

Unlock a group of properties.

Parameters
propsthe 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