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