SDL 3.0
|
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_begin_code.h>
#include <SDL3/SDL_close_code.h>
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) |
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.
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.
Definition at line 187 of file SDL_properties.h.
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.
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.
Definition at line 499 of file SDL_properties.h.
typedef Uint32 SDL_PropertiesID |
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:
void*
pointer types.Properties can be removed from a group by using SDL_ClearProperty. SDL properties ID
Definition at line 66 of file SDL_properties.h.
enum SDL_PropertyType |
SDL property type
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.
bool SDL_ClearProperty | ( | SDL_PropertiesID | props, |
const char * | name | ||
) |
Clear a property from a group of properties.
props | the properties to modify. |
name | the name of the property to clear. |
\threadsafety It is safe to call this function from any thread.
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.
src | the properties to copy. |
dst | the destination properties. |
\threadsafety It is safe to call this function from any thread.
SDL_PropertiesID SDL_CreateProperties | ( | void | ) |
Create a group of properties.
All properties are automatically destroyed when SDL_Quit() is called.
\threadsafety It is safe to call this function from any thread.
void SDL_DestroyProperties | ( | SDL_PropertiesID | props | ) |
Destroy a group of properties.
All properties are deleted and their cleanup functions will be called, if any.
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.
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.
props | the properties to query. |
callback | the function to call for each property. |
userdata | a pointer that is passed to callback . |
\threadsafety It is safe to call this function from any thread.
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.
props | the properties to query. |
name | the name of the property to query. |
default_value | the default value of the property. |
default_value
if it is not set or not a boolean property.\threadsafety It is safe to call this function from any thread.
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.
props | the properties to query. |
name | the name of the property to query. |
default_value | the default value of the property. |
default_value
if it is not set or not a float property.\threadsafety It is safe to call this function from any thread.
SDL_PropertiesID SDL_GetGlobalProperties | ( | void | ) |
Get the global SDL properties.
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.
props | the properties to query. |
name | the name of the property to query. |
default_value | the default value of the property. |
default_value
if it is not set or not a number property.\threadsafety It is safe to call this function from any thread.
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.
props | the properties to query. |
name | the name of the property to query. |
default_value | the default value of the property. |
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().
SDL_PropertyType SDL_GetPropertyType | ( | SDL_PropertiesID | props, |
const char * | name | ||
) |
Get the type of a property in a group of properties.
props | the properties to query. |
name | the name of the property to query. |
\threadsafety It is safe to call this function from any thread.
const char * SDL_GetStringProperty | ( | SDL_PropertiesID | props, |
const char * | name, | ||
const char * | default_value | ||
) |
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. |
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().
bool SDL_HasProperty | ( | SDL_PropertiesID | props, |
const char * | name | ||
) |
Return whether a property exists in a group of properties.
props | the properties to query. |
name | the name of the property to query. |
\threadsafety It is safe to call this function from any thread.
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.
props | the properties to lock. |
\threadsafety It is safe to call this function from any thread.
bool SDL_SetBooleanProperty | ( | SDL_PropertiesID | props, |
const char * | name, | ||
bool | value | ||
) |
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. |
\threadsafety It is safe to call this function from any thread.
bool SDL_SetFloatProperty | ( | SDL_PropertiesID | props, |
const char * | name, | ||
float | value | ||
) |
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. |
\threadsafety It is safe to call this function from any thread.
bool SDL_SetNumberProperty | ( | SDL_PropertiesID | props, |
const char * | name, | ||
Sint64 | value | ||
) |
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. |
\threadsafety It is safe to call this function from any thread.
bool SDL_SetPointerProperty | ( | SDL_PropertiesID | props, |
const char * | name, | ||
void * | value | ||
) |
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. |
\threadsafety It is safe to call this function from any thread.
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.
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. |
\threadsafety It is safe to call this function from any thread.
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.
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. |
\threadsafety It is safe to call this function from any thread.
void SDL_UnlockProperties | ( | SDL_PropertiesID | props | ) |
Unlock a group of properties.
props | the properties to unlock. |
\threadsafety It is safe to call this function from any thread.