SDL 3.0
SDL_properties.h
Go to the documentation of this file.
1/*
2 Simple DiretMedia Layer
3 Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
4
5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the authors be held liable for any damages
7 arising from the use of this software.
8
9 Permission is granted to anyone to use this software for any purpose,
10 including commercial applications, and to alter it and redistribute it
11 freely, subject to the following restrictions:
12
13 1. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
17 2. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
19 3. This notice may not be removed or altered from any source distribution.
20*/
21
22/**
23 * \file SDL_properties.h
24 *
25 * Header file for SDL properties.
26 */
27
28#ifndef SDL_properties_h_
29#define SDL_properties_h_
30
31#include <SDL3/SDL_begin_code.h>
32/* Set up for C function definitions, even when using C++ */
33#ifdef __cplusplus
34extern "C" {
35#endif
36
37/**
38 * SDL properties ID
39 */
41
42/**
43 * SDL property type
44 */
54
55/**
56 * Get the global SDL properties
57 *
58 * \returns a valid property ID on success or 0 on failure; call
59 * SDL_GetError() for more information.
60 *
61 * \since This function is available since SDL 3.0.0.
62 *
63 * \sa SDL_GetProperty
64 * \sa SDL_SetProperty
65 */
66extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void);
67
68/**
69 * Create a set of properties
70 *
71 * All properties are automatically destroyed when SDL_Quit() is called.
72 *
73 * \returns an ID for a new set of properties, or 0 on failure; call
74 * SDL_GetError() for more information.
75 *
76 * \threadsafety It is safe to call this function from any thread.
77 *
78 * \since This function is available since SDL 3.0.0.
79 *
80 * \sa SDL_DestroyProperties
81 */
82extern DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void);
83
84/**
85 * Lock a set of properties
86 *
87 * Obtain a multi-threaded lock for these properties. Other threads will wait
88 * while trying to lock these properties until they are unlocked. Properties
89 * must be unlocked before they are destroyed.
90 *
91 * The lock is automatically taken when setting individual properties, this
92 * function is only needed when you want to set several properties atomically
93 * or want to guarantee that properties being queried aren't freed in another
94 * thread.
95 *
96 * \param props the properties to lock
97 * \returns 0 on success or a negative error code on failure; call
98 * SDL_GetError() for more information.
99 *
100 * \threadsafety It is safe to call this function from any thread.
101 *
102 * \since This function is available since SDL 3.0.0.
103 *
104 * \sa SDL_UnlockProperties
105 */
106extern DECLSPEC int SDLCALL SDL_LockProperties(SDL_PropertiesID props);
107
108/**
109 * Unlock a set of properties
110 *
111 * \param props the properties to unlock
112 *
113 * \threadsafety It is safe to call this function from any thread.
114 *
115 * \since This function is available since SDL 3.0.0.
116 *
117 * \sa SDL_LockProperties
118 */
119extern DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);
120
121/**
122 * Set a property on a set of properties with a cleanup function that is
123 * called when the property is deleted
124 *
125 * \param props the properties to modify
126 * \param name the name of the property to modify
127 * \param value the new value of the property, or NULL to delete the property
128 * \param cleanup the function to call when this property is deleted, or NULL
129 * if no cleanup is necessary
130 * \param userdata a pointer that is passed to the cleanup function
131 * \returns 0 on success or a negative error code on failure; call
132 * SDL_GetError() for more information.
133 *
134 * \threadsafety It is safe to call this function from any thread.
135 *
136 * \since This function is available since SDL 3.0.0.
137 *
138 * \sa SDL_GetProperty
139 * \sa SDL_SetProperty
140 */
141extern DECLSPEC int SDLCALL SDL_SetPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, void (SDLCALL *cleanup)(void *userdata, void *value), void *userdata);
142
143/**
144 * Set a property on a set of properties
145 *
146 * \param props the properties to modify
147 * \param name the name of the property to modify
148 * \param value the new value of the property, or NULL to delete the property
149 * \returns 0 on success or a negative error code on failure; call
150 * SDL_GetError() for more information.
151 *
152 * \threadsafety It is safe to call this function from any thread.
153 *
154 * \since This function is available since SDL 3.0.0.
155 *
156 * \sa SDL_GetProperty
157 * \sa SDL_SetPropertyWithCleanup
158 */
159extern DECLSPEC int SDLCALL SDL_SetProperty(SDL_PropertiesID props, const char *name, void *value);
160
161/**
162 * Set a string property on a set of properties
163 *
164 * \param props the properties to modify
165 * \param name the name of the property to modify
166 * \param value the new value of the property, or NULL to delete the property
167 * \returns 0 on success or a negative error code on failure; call
168 * SDL_GetError() for more information.
169 *
170 * \threadsafety It is safe to call this function from any thread.
171 *
172 * \since This function is available since SDL 3.0.0.
173 *
174 * \sa SDL_GetStringProperty
175 */
176extern DECLSPEC int SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value);
177
178/**
179 * Set an integer property on a set of properties
180 *
181 * \param props the properties to modify
182 * \param name the name of the property to modify
183 * \param value the new value of the property
184 * \returns 0 on success or a negative error code on failure; call
185 * SDL_GetError() for more information.
186 *
187 * \threadsafety It is safe to call this function from any thread.
188 *
189 * \since This function is available since SDL 3.0.0.
190 *
191 * \sa SDL_GetNumberProperty
192 */
193extern DECLSPEC int SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value);
194
195/**
196 * Set a floating point property on a set of properties
197 *
198 * \param props the properties to modify
199 * \param name the name of the property to modify
200 * \param value the new value of the property
201 * \returns 0 on success or a negative error code on failure; call
202 * SDL_GetError() for more information.
203 *
204 * \threadsafety It is safe to call this function from any thread.
205 *
206 * \since This function is available since SDL 3.0.0.
207 *
208 * \sa SDL_GetFloatProperty
209 */
210extern DECLSPEC int SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value);
211
212/**
213 * Set a boolean property on a set of properties
214 *
215 * \param props the properties to modify
216 * \param name the name of the property to modify
217 * \param value the new value of the property
218 * \returns 0 on success or a negative error code on failure; call
219 * SDL_GetError() for more information.
220 *
221 * \threadsafety It is safe to call this function from any thread.
222 *
223 * \since This function is available since SDL 3.0.0.
224 *
225 * \sa SDL_GetBooleanProperty
226 */
227extern DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool value);
228
229/**
230 * Get the type of a property on a set of properties
231 *
232 * \param props the properties to query
233 * \param name the name of the property to query
234 * \returns the type of the property, or SDL_PROPERTY_TYPE_INVALID if it is
235 * not set.
236 *
237 * \threadsafety It is safe to call this function from any thread.
238 *
239 * \since This function is available since SDL 3.0.0.
240 */
241extern DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesID props, const char *name);
242
243/**
244 * Get a property on a set of properties
245 *
246 * By convention, the names of properties that SDL exposes on objects will
247 * start with "SDL.", and properties that SDL uses internally will start with
248 * "SDL.internal.". These should be considered read-only and should not be
249 * modified by applications.
250 *
251 * \param props the properties to query
252 * \param name the name of the property to query
253 * \param default_value the default value of the property
254 * \returns the value of the property, or `default_value` if it is not set or
255 * not a pointer property.
256 *
257 * \threadsafety It is safe to call this function from any thread, although
258 * the data returned is not protected and could potentially be
259 * freed if you call SDL_SetProperty() or SDL_ClearProperty() on
260 * these properties from another thread. If you need to avoid
261 * this, use SDL_LockProperties() and SDL_UnlockProperties().
262 *
263 * \since This function is available since SDL 3.0.0.
264 *
265 * \sa SDL_GetPropertyType
266 * \sa SDL_SetProperty
267 */
268extern DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const char *name, void *default_value);
269
270/**
271 * Get a string property on a set of properties
272 *
273 * \param props the properties to query
274 * \param name the name of the property to query
275 * \param default_value the default value of the property
276 * \returns the value of the property, or `default_value` if it is not set or
277 * not a string property.
278 *
279 * \threadsafety It is safe to call this function from any thread.
280 *
281 * \since This function is available since SDL 3.0.0.
282 *
283 * \sa SDL_GetPropertyType
284 * \sa SDL_SetStringProperty
285 */
286extern DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID props, const char *name, const char *default_value);
287
288/**
289 * Get a number property on a set of properties
290 *
291 * You can use SDL_GetPropertyType() to query whether the property exists and
292 * is a number property.
293 *
294 * \param props the properties to query
295 * \param name the name of the property to query
296 * \param default_value the default value of the property
297 * \returns the value of the property, or `default_value` if it is not set or
298 * not a number property.
299 *
300 * \threadsafety It is safe to call this function from any thread.
301 *
302 * \since This function is available since SDL 3.0.0.
303 *
304 * \sa SDL_GetPropertyType
305 * \sa SDL_SetNumberProperty
306 */
307extern DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 default_value);
308
309/**
310 * Get a floating point property on a set of properties
311 *
312 * You can use SDL_GetPropertyType() to query whether the property exists and
313 * is a floating point property.
314 *
315 * \param props the properties to query
316 * \param name the name of the property to query
317 * \param default_value the default value of the property
318 * \returns the value of the property, or `default_value` if it is not set or
319 * not a float property.
320 *
321 * \threadsafety It is safe to call this function from any thread.
322 *
323 * \since This function is available since SDL 3.0.0.
324 *
325 * \sa SDL_GetPropertyType
326 * \sa SDL_SetFloatProperty
327 */
328extern DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, const char *name, float default_value);
329
330/**
331 * Get a boolean property on a set of properties
332 *
333 * You can use SDL_GetPropertyType() to query whether the property exists and
334 * is a boolean property.
335 *
336 * \param props the properties to query
337 * \param name the name of the property to query
338 * \param default_value the default value of the property
339 * \returns the value of the property, or `default_value` if it is not set or
340 * not a float property.
341 *
342 * \threadsafety It is safe to call this function from any thread.
343 *
344 * \since This function is available since SDL 3.0.0.
345 *
346 * \sa SDL_GetPropertyType
347 * \sa SDL_SetBooleanProperty
348 */
349extern DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool default_value);
350
351/**
352 * Clear a property on a set of properties
353 *
354 * \param props the properties to modify
355 * \param name the name of the property to clear
356 * \returns 0 on success or a negative error code on failure; call
357 * SDL_GetError() for more information.
358 *
359 * \threadsafety It is safe to call this function from any thread.
360 *
361 * \since This function is available since SDL 3.0.0.
362 *
363 * \sa SDL_GetProperty
364 */
365extern DECLSPEC int SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name);
366
367typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_PropertiesID props, const char *name);
368
369/**
370 * Enumerate the properties on a set of properties
371 *
372 * The callback function is called for each property on the set of properties.
373 * The properties are locked during enumeration.
374 *
375 * \param props the properties to query
376 * \param callback the function to call for each property
377 * \param userdata a pointer that is passed to `callback`
378 * \returns 0 on success or a negative error code on failure; call
379 * SDL_GetError() for more information.
380 *
381 * \threadsafety It is safe to call this function from any thread.
382 *
383 * \since This function is available since SDL 3.0.0.
384 */
385extern DECLSPEC int SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata);
386
387/**
388 * Destroy a set of properties
389 *
390 * All properties are deleted and their cleanup functions will be called, if
391 * any.
392 *
393 * \param props the properties to destroy
394 *
395 * \threadsafety This function should not be called while these properties are
396 * locked or other threads might be setting or getting values
397 * from these properties.
398 *
399 * \since This function is available since SDL 3.0.0.
400 *
401 * \sa SDL_CreateProperties
402 */
403extern DECLSPEC void SDLCALL SDL_DestroyProperties(SDL_PropertiesID props);
404
405/* Ends C function definitions when using C++ */
406#ifdef __cplusplus
407}
408#endif
409#include <SDL3/SDL_close_code.h>
410
411#endif /* SDL_properties_h_ */
Sint64 SDL_GetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 default_value)
int SDL_SetPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, void(*cleanup)(void *userdata, void *value), void *userdata)
int SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value)
float SDL_GetFloatProperty(SDL_PropertiesID props, const char *name, float default_value)
int SDL_LockProperties(SDL_PropertiesID props)
int SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata)
void * SDL_GetProperty(SDL_PropertiesID props, const char *name, void *default_value)
int SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value)
Uint32 SDL_PropertiesID
SDL_PropertiesID SDL_GetGlobalProperties(void)
void(* SDL_EnumeratePropertiesCallback)(void *userdata, SDL_PropertiesID props, const char *name)
int SDL_ClearProperty(SDL_PropertiesID props, const char *name)
const char * SDL_GetStringProperty(SDL_PropertiesID props, const char *name, const char *default_value)
int SDL_SetProperty(SDL_PropertiesID props, const char *name, void *value)
SDL_PropertyType SDL_GetPropertyType(SDL_PropertiesID props, const char *name)
int SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool value)
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
SDL_PropertiesID SDL_CreateProperties(void)
void SDL_DestroyProperties(SDL_PropertiesID props)
void SDL_UnlockProperties(SDL_PropertiesID props)
int SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value)
SDL_bool SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool default_value)
int64_t Sint64
Definition SDL_stdinc.h:181
int SDL_bool
Definition SDL_stdinc.h:137
uint32_t Uint32
Definition SDL_stdinc.h:174