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_stdinc.h>
32#include <SDL3/SDL_error.h>
33
34#include <SDL3/SDL_begin_code.h>
35/* Set up for C function definitions, even when using C++ */
36#ifdef __cplusplus
37extern "C" {
38#endif
39
40/**
41 * SDL properties ID
42 *
43 * \since This datatype is available since SDL 3.0.0.
44 */
46
47/**
48 * SDL property type
49 *
50 * \since This enum is available since SDL 3.0.0.
51 */
61
62/**
63 * Get the global SDL properties.
64 *
65 * \returns a valid property ID on success or 0 on failure; call
66 * SDL_GetError() for more information.
67 *
68 * \since This function is available since SDL 3.0.0.
69 *
70 * \sa SDL_GetProperty
71 * \sa SDL_SetProperty
72 */
73extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void);
74
75/**
76 * Create a set of properties.
77 *
78 * All properties are automatically destroyed when SDL_Quit() is called.
79 *
80 * \returns an ID for a new set of properties, or 0 on failure; call
81 * SDL_GetError() for more information.
82 *
83 * \threadsafety It is safe to call this function from any thread.
84 *
85 * \since This function is available since SDL 3.0.0.
86 *
87 * \sa SDL_DestroyProperties
88 */
89extern DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void);
90
91/**
92 * Copy a set of properties.
93 *
94 * Copy all the properties from one set of properties to another, with the
95 * exception of properties requiring cleanup (set using
96 * SDL_SetPropertyWithCleanup()), which will not be copied. Any property that
97 * already exists on `dst` will be overwritten.
98 *
99 * \param src the properties to copy
100 * \param dst the destination properties
101 * \returns 0 on success or a negative error code on failure; call
102 * SDL_GetError() for more information.
103 *
104 * \threadsafety It is safe to call this function from any thread.
105 *
106 * \since This function is available since SDL 3.0.0.
107 */
108extern DECLSPEC int SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst);
109
110/**
111 * Lock a set of properties.
112 *
113 * Obtain a multi-threaded lock for these properties. Other threads will wait
114 * while trying to lock these properties until they are unlocked. Properties
115 * must be unlocked before they are destroyed.
116 *
117 * The lock is automatically taken when setting individual properties, this
118 * function is only needed when you want to set several properties atomically
119 * or want to guarantee that properties being queried aren't freed in another
120 * thread.
121 *
122 * \param props the properties to lock
123 * \returns 0 on success or a negative error code on failure; call
124 * SDL_GetError() for more information.
125 *
126 * \threadsafety It is safe to call this function from any thread.
127 *
128 * \since This function is available since SDL 3.0.0.
129 *
130 * \sa SDL_UnlockProperties
131 */
132extern DECLSPEC int SDLCALL SDL_LockProperties(SDL_PropertiesID props);
133
134/**
135 * Unlock a set of properties.
136 *
137 * \param props the properties to unlock
138 *
139 * \threadsafety It is safe to call this function from any thread.
140 *
141 * \since This function is available since SDL 3.0.0.
142 *
143 * \sa SDL_LockProperties
144 */
145extern DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);
146
147/**
148 * Set a property on a set of properties with a cleanup function that is
149 * called when the property is deleted.
150 *
151 * The cleanup function is also called if setting the property fails for any
152 * reason.
153 *
154 * \param props the properties to modify
155 * \param name the name of the property to modify
156 * \param value the new value of the property, or NULL to delete the property
157 * \param cleanup the function to call when this property is deleted, or NULL
158 * if no cleanup is necessary
159 * \param userdata a pointer that is passed to the cleanup function
160 * \returns 0 on success or a negative error code on failure; call
161 * SDL_GetError() for more information.
162 *
163 * \threadsafety It is safe to call this function from any thread.
164 *
165 * \since This function is available since SDL 3.0.0.
166 *
167 * \sa SDL_GetProperty
168 * \sa SDL_SetProperty
169 */
170extern DECLSPEC int SDLCALL SDL_SetPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, void (SDLCALL *cleanup)(void *userdata, void *value), void *userdata);
171
172/**
173 * Set a property on a set of properties.
174 *
175 * \param props the properties to modify
176 * \param name the name of the property to modify
177 * \param value the new value of the property, or NULL to delete the property
178 * \returns 0 on success or a negative error code on failure; call
179 * SDL_GetError() for more information.
180 *
181 * \threadsafety It is safe to call this function from any thread.
182 *
183 * \since This function is available since SDL 3.0.0.
184 *
185 * \sa SDL_GetProperty
186 * \sa SDL_HasProperty
187 * \sa SDL_SetBooleanProperty
188 * \sa SDL_SetFloatProperty
189 * \sa SDL_SetNumberProperty
190 * \sa SDL_SetPropertyWithCleanup
191 * \sa SDL_SetStringProperty
192 */
193extern DECLSPEC int SDLCALL SDL_SetProperty(SDL_PropertiesID props, const char *name, void *value);
194
195/**
196 * Set a string property on a set of properties.
197 *
198 * This function makes a copy of the string; the caller does not have to
199 * preserve the data after this call completes.
200 *
201 * \param props the properties to modify
202 * \param name the name of the property to modify
203 * \param value the new value of the property, or NULL to delete the property
204 * \returns 0 on success or a negative error code on failure; call
205 * SDL_GetError() for more information.
206 *
207 * \threadsafety It is safe to call this function from any thread.
208 *
209 * \since This function is available since SDL 3.0.0.
210 *
211 * \sa SDL_GetStringProperty
212 */
213extern DECLSPEC int SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value);
214
215/**
216 * Set an integer property on a set of properties.
217 *
218 * \param props the properties to modify
219 * \param name the name of the property to modify
220 * \param value the new value of the property
221 * \returns 0 on success or a negative error code on failure; call
222 * SDL_GetError() for more information.
223 *
224 * \threadsafety It is safe to call this function from any thread.
225 *
226 * \since This function is available since SDL 3.0.0.
227 *
228 * \sa SDL_GetNumberProperty
229 */
230extern DECLSPEC int SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value);
231
232/**
233 * Set a floating point property on a set of properties.
234 *
235 * \param props the properties to modify
236 * \param name the name of the property to modify
237 * \param value the new value of the property
238 * \returns 0 on success or a negative error code on failure; call
239 * SDL_GetError() for more information.
240 *
241 * \threadsafety It is safe to call this function from any thread.
242 *
243 * \since This function is available since SDL 3.0.0.
244 *
245 * \sa SDL_GetFloatProperty
246 */
247extern DECLSPEC int SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value);
248
249/**
250 * Set a boolean property on a set of properties.
251 *
252 * \param props the properties to modify
253 * \param name the name of the property to modify
254 * \param value the new value of the property
255 * \returns 0 on success or a negative error code on failure; call
256 * SDL_GetError() for more information.
257 *
258 * \threadsafety It is safe to call this function from any thread.
259 *
260 * \since This function is available since SDL 3.0.0.
261 *
262 * \sa SDL_GetBooleanProperty
263 */
264extern DECLSPEC int SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool value);
265
266/**
267 * Return whether a property exists in a set of properties.
268 *
269 * \param props the properties to query
270 * \param name the name of the property to query
271 * \returns SDL_TRUE if the property exists, or SDL_FALSE if it doesn't.
272 *
273 * \threadsafety It is safe to call this function from any thread.
274 *
275 * \since This function is available since SDL 3.0.0.
276 *
277 * \sa SDL_GetPropertyType
278 */
279extern DECLSPEC SDL_bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name);
280
281/**
282 * Get the type of a property on a set of properties.
283 *
284 * \param props the properties to query
285 * \param name the name of the property to query
286 * \returns the type of the property, or SDL_PROPERTY_TYPE_INVALID if it is
287 * not set.
288 *
289 * \threadsafety It is safe to call this function from any thread.
290 *
291 * \since This function is available since SDL 3.0.0.
292 *
293 * \sa SDL_HasProperty
294 */
295extern DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesID props, const char *name);
296
297/**
298 * Get a property on a set of properties.
299 *
300 * By convention, the names of properties that SDL exposes on objects will
301 * start with "SDL.", and properties that SDL uses internally will start with
302 * "SDL.internal.". These should be considered read-only and should not be
303 * modified by applications.
304 *
305 * \param props the properties to query
306 * \param name the name of the property to query
307 * \param default_value the default value of the property
308 * \returns the value of the property, or `default_value` if it is not set or
309 * not a pointer property.
310 *
311 * \threadsafety It is safe to call this function from any thread, although
312 * the data returned is not protected and could potentially be
313 * freed if you call SDL_SetProperty() or SDL_ClearProperty() on
314 * these properties from another thread. If you need to avoid
315 * this, use SDL_LockProperties() and SDL_UnlockProperties().
316 *
317 * \since This function is available since SDL 3.0.0.
318 *
319 * \sa SDL_GetBooleanProperty
320 * \sa SDL_GetFloatProperty
321 * \sa SDL_GetNumberProperty
322 * \sa SDL_GetPropertyType
323 * \sa SDL_GetStringProperty
324 * \sa SDL_HasProperty
325 * \sa SDL_SetProperty
326 */
327extern DECLSPEC void *SDLCALL SDL_GetProperty(SDL_PropertiesID props, const char *name, void *default_value);
328
329/**
330 * Get a string property on a set of properties.
331 *
332 * \param props the properties to query
333 * \param name the name of the property to query
334 * \param default_value the default value of the property
335 * \returns the value of the property, or `default_value` if it is not set or
336 * not a string property.
337 *
338 * \threadsafety It is safe to call this function from any thread.
339 *
340 * \since This function is available since SDL 3.0.0.
341 *
342 * \sa SDL_GetPropertyType
343 * \sa SDL_HasProperty
344 * \sa SDL_SetStringProperty
345 */
346extern DECLSPEC const char *SDLCALL SDL_GetStringProperty(SDL_PropertiesID props, const char *name, const char *default_value);
347
348/**
349 * Get a number property on a set of properties.
350 *
351 * You can use SDL_GetPropertyType() to query whether the property exists and
352 * is a number property.
353 *
354 * \param props the properties to query
355 * \param name the name of the property to query
356 * \param default_value the default value of the property
357 * \returns the value of the property, or `default_value` if it is not set or
358 * not a number property.
359 *
360 * \threadsafety It is safe to call this function from any thread.
361 *
362 * \since This function is available since SDL 3.0.0.
363 *
364 * \sa SDL_GetPropertyType
365 * \sa SDL_HasProperty
366 * \sa SDL_SetNumberProperty
367 */
368extern DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 default_value);
369
370/**
371 * Get a floating point property on a set of properties.
372 *
373 * You can use SDL_GetPropertyType() to query whether the property exists and
374 * is a floating point property.
375 *
376 * \param props the properties to query
377 * \param name the name of the property to query
378 * \param default_value the default value of the property
379 * \returns the value of the property, or `default_value` if it is not set or
380 * not a float property.
381 *
382 * \threadsafety It is safe to call this function from any thread.
383 *
384 * \since This function is available since SDL 3.0.0.
385 *
386 * \sa SDL_GetPropertyType
387 * \sa SDL_HasProperty
388 * \sa SDL_SetFloatProperty
389 */
390extern DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, const char *name, float default_value);
391
392/**
393 * Get a boolean property on a set of properties.
394 *
395 * You can use SDL_GetPropertyType() to query whether the property exists and
396 * is a boolean property.
397 *
398 * \param props the properties to query
399 * \param name the name of the property to query
400 * \param default_value the default value of the property
401 * \returns the value of the property, or `default_value` if it is not set or
402 * not a float property.
403 *
404 * \threadsafety It is safe to call this function from any thread.
405 *
406 * \since This function is available since SDL 3.0.0.
407 *
408 * \sa SDL_GetPropertyType
409 * \sa SDL_HasProperty
410 * \sa SDL_SetBooleanProperty
411 */
412extern DECLSPEC SDL_bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, SDL_bool default_value);
413
414/**
415 * Clear a property on a set of properties.
416 *
417 * \param props the properties to modify
418 * \param name the name of the property to clear
419 * \returns 0 on success or a negative error code on failure; call
420 * SDL_GetError() for more information.
421 *
422 * \threadsafety It is safe to call this function from any thread.
423 *
424 * \since This function is available since SDL 3.0.0.
425 */
426extern DECLSPEC int SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name);
427
428typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_PropertiesID props, const char *name);
429
430/**
431 * Enumerate the properties on a set of properties.
432 *
433 * The callback function is called for each property on the set of properties.
434 * The properties are locked during enumeration.
435 *
436 * \param props the properties to query
437 * \param callback the function to call for each property
438 * \param userdata a pointer that is passed to `callback`
439 * \returns 0 on success or a negative error code on failure; call
440 * SDL_GetError() for more information.
441 *
442 * \threadsafety It is safe to call this function from any thread.
443 *
444 * \since This function is available since SDL 3.0.0.
445 */
446extern DECLSPEC int SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata);
447
448/**
449 * Destroy a set of properties.
450 *
451 * All properties are deleted and their cleanup functions will be called, if
452 * any.
453 *
454 * \param props the properties to destroy
455 *
456 * \threadsafety This function should not be called while these properties are
457 * locked or other threads might be setting or getting values
458 * from these properties.
459 *
460 * \since This function is available since SDL 3.0.0.
461 *
462 * \sa SDL_CreateProperties
463 */
464extern DECLSPEC void SDLCALL SDL_DestroyProperties(SDL_PropertiesID props);
465
466/* Ends C function definitions when using C++ */
467#ifdef __cplusplus
468}
469#endif
470#include <SDL3/SDL_close_code.h>
471
472#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)
int SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst)
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)
SDL_bool SDL_HasProperty(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:233
int SDL_bool
Definition SDL_stdinc.h:170
uint32_t Uint32
Definition SDL_stdinc.h:224