1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2025 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 * # CategoryProperties
24 *
25 * A property is a variable that can be created and retrieved by name at
26 * runtime.
27 *
28 * All properties are part of a property group (SDL_PropertiesID). A property
29 * group can be created with the SDL_CreateProperties function and destroyed
30 * with the SDL_DestroyProperties function.
31 *
32 * Properties can be added to and retrieved from a property group through the
33 * following functions:
34 *
35 * - SDL_SetPointerProperty and SDL_GetPointerProperty operate on `void*`
36 * pointer types.
37 * - SDL_SetStringProperty and SDL_GetStringProperty operate on string types.
38 * - SDL_SetNumberProperty and SDL_GetNumberProperty operate on signed 64-bit
39 * integer types.
40 * - SDL_SetFloatProperty and SDL_GetFloatProperty operate on floating point
41 * types.
42 * - SDL_SetBooleanProperty and SDL_GetBooleanProperty operate on boolean
43 * types.
44 *
45 * Properties can be removed from a group by using SDL_ClearProperty.
46 */
47
48
49#ifndef SDL_properties_h_
50#define SDL_properties_h_
51
52#include <SDL3/SDL_stdinc.h>
53#include <SDL3/SDL_error.h>
54
55#include <SDL3/SDL_begin_code.h>
56/* Set up for C function definitions, even when using C++ */
57#ifdef __cplusplus
58extern "C" {
59#endif
60
61/**
62 * SDL properties ID
63 *
64 * \since This datatype is available since SDL 3.2.0.
65 */
66typedef Uint32 SDL_PropertiesID;
67
68/**
69 * SDL property type
70 *
71 * \since This enum is available since SDL 3.2.0.
72 */
73typedef enum SDL_PropertyType
74{
75 SDL_PROPERTY_TYPE_INVALID,
76 SDL_PROPERTY_TYPE_POINTER,
77 SDL_PROPERTY_TYPE_STRING,
78 SDL_PROPERTY_TYPE_NUMBER,
79 SDL_PROPERTY_TYPE_FLOAT,
80 SDL_PROPERTY_TYPE_BOOLEAN
81} SDL_PropertyType;
82
83/**
84 * Get the global SDL properties.
85 *
86 * \returns a valid property ID on success or 0 on failure; call
87 * SDL_GetError() for more information.
88 *
89 * \since This function is available since SDL 3.2.0.
90 */
91extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetGlobalProperties(void);
92
93/**
94 * Create a group of properties.
95 *
96 * All properties are automatically destroyed when SDL_Quit() is called.
97 *
98 * \returns an ID for a new group of properties, or 0 on failure; call
99 * SDL_GetError() for more information.
100 *
101 * \threadsafety It is safe to call this function from any thread.
102 *
103 * \since This function is available since SDL 3.2.0.
104 *
105 * \sa SDL_DestroyProperties
106 */
107extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_CreateProperties(void);
108
109/**
110 * Copy a group of properties.
111 *
112 * Copy all the properties from one group of properties to another, with the
113 * exception of properties requiring cleanup (set using
114 * SDL_SetPointerPropertyWithCleanup()), which will not be copied. Any
115 * property that already exists on `dst` will be overwritten.
116 *
117 * \param src the properties to copy.
118 * \param dst the destination properties.
119 * \returns true on success or false on failure; call SDL_GetError() for more
120 * information.
121 *
122 * \threadsafety It is safe to call this function from any thread.
123 *
124 * \since This function is available since SDL 3.2.0.
125 */
126extern SDL_DECLSPEC bool SDLCALL SDL_CopyProperties(SDL_PropertiesID src, SDL_PropertiesID dst);
127
128/**
129 * Lock a group of properties.
130 *
131 * Obtain a multi-threaded lock for these properties. Other threads will wait
132 * while trying to lock these properties until they are unlocked. Properties
133 * must be unlocked before they are destroyed.
134 *
135 * The lock is automatically taken when setting individual properties, this
136 * function is only needed when you want to set several properties atomically
137 * or want to guarantee that properties being queried aren't freed in another
138 * thread.
139 *
140 * \param props the properties to lock.
141 * \returns true on success or false on failure; call SDL_GetError() for more
142 * information.
143 *
144 * \threadsafety It is safe to call this function from any thread.
145 *
146 * \since This function is available since SDL 3.2.0.
147 *
148 * \sa SDL_UnlockProperties
149 */
150extern SDL_DECLSPEC bool SDLCALL SDL_LockProperties(SDL_PropertiesID props);
151
152/**
153 * Unlock a group of properties.
154 *
155 * \param props the properties to unlock.
156 *
157 * \threadsafety It is safe to call this function from any thread.
158 *
159 * \since This function is available since SDL 3.2.0.
160 *
161 * \sa SDL_LockProperties
162 */
163extern SDL_DECLSPEC void SDLCALL SDL_UnlockProperties(SDL_PropertiesID props);
164
165/**
166 * A callback used to free resources when a property is deleted.
167 *
168 * This should release any resources associated with `value` that are no
169 * longer needed.
170 *
171 * This callback is set per-property. Different properties in the same group
172 * can have different cleanup callbacks.
173 *
174 * This callback will be called _during_ SDL_SetPointerPropertyWithCleanup if
175 * the function fails for any reason.
176 *
177 * \param userdata an app-defined pointer passed to the callback.
178 * \param value the pointer assigned to the property to clean up.
179 *
180 * \threadsafety This callback may fire without any locks held; if this is a
181 * concern, the app should provide its own locking.
182 *
183 * \since This datatype is available since SDL 3.2.0.
184 *
185 * \sa SDL_SetPointerPropertyWithCleanup
186 */
187typedef void (SDLCALL *SDL_CleanupPropertyCallback)(void *userdata, void *value);
188
189/**
190 * Set a pointer property in a group of properties with a cleanup function
191 * that is called when the property is deleted.
192 *
193 * The cleanup function is also called if setting the property fails for any
194 * reason.
195 *
196 * For simply setting basic data types, like numbers, bools, or strings, use
197 * SDL_SetNumberProperty, SDL_SetBooleanProperty, or SDL_SetStringProperty
198 * instead, as those functions will handle cleanup on your behalf. This
199 * function is only for more complex, custom data.
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 * \param cleanup the function to call when this property is deleted, or NULL
205 * if no cleanup is necessary.
206 * \param userdata a pointer that is passed to the cleanup function.
207 * \returns true on success or false on failure; call SDL_GetError() for more
208 * information.
209 *
210 * \threadsafety It is safe to call this function from any thread.
211 *
212 * \since This function is available since SDL 3.2.0.
213 *
214 * \sa SDL_GetPointerProperty
215 * \sa SDL_SetPointerProperty
216 * \sa SDL_CleanupPropertyCallback
217 */
218extern SDL_DECLSPEC bool SDLCALL SDL_SetPointerPropertyWithCleanup(SDL_PropertiesID props, const char *name, void *value, SDL_CleanupPropertyCallback cleanup, void *userdata);
219
220/**
221 * Set a pointer property in a group of properties.
222 *
223 * \param props the properties to modify.
224 * \param name the name of the property to modify.
225 * \param value the new value of the property, or NULL to delete the property.
226 * \returns true on success or false on failure; call SDL_GetError() for more
227 * information.
228 *
229 * \threadsafety It is safe to call this function from any thread.
230 *
231 * \since This function is available since SDL 3.2.0.
232 *
233 * \sa SDL_GetPointerProperty
234 * \sa SDL_HasProperty
235 * \sa SDL_SetBooleanProperty
236 * \sa SDL_SetFloatProperty
237 * \sa SDL_SetNumberProperty
238 * \sa SDL_SetPointerPropertyWithCleanup
239 * \sa SDL_SetStringProperty
240 */
241extern SDL_DECLSPEC bool SDLCALL SDL_SetPointerProperty(SDL_PropertiesID props, const char *name, void *value);
242
243/**
244 * Set a string property in a group of properties.
245 *
246 * This function makes a copy of the string; the caller does not have to
247 * preserve the data after this call completes.
248 *
249 * \param props the properties to modify.
250 * \param name the name of the property to modify.
251 * \param value the new value of the property, or NULL to delete the property.
252 * \returns true on success or false on failure; call SDL_GetError() for more
253 * information.
254 *
255 * \threadsafety It is safe to call this function from any thread.
256 *
257 * \since This function is available since SDL 3.2.0.
258 *
259 * \sa SDL_GetStringProperty
260 */
261extern SDL_DECLSPEC bool SDLCALL SDL_SetStringProperty(SDL_PropertiesID props, const char *name, const char *value);
262
263/**
264 * Set an integer property in a group of properties.
265 *
266 * \param props the properties to modify.
267 * \param name the name of the property to modify.
268 * \param value the new value of the property.
269 * \returns true on success or false on failure; call SDL_GetError() for more
270 * information.
271 *
272 * \threadsafety It is safe to call this function from any thread.
273 *
274 * \since This function is available since SDL 3.2.0.
275 *
276 * \sa SDL_GetNumberProperty
277 */
278extern SDL_DECLSPEC bool SDLCALL SDL_SetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 value);
279
280/**
281 * Set a floating point property in a group of properties.
282 *
283 * \param props the properties to modify.
284 * \param name the name of the property to modify.
285 * \param value the new value of the property.
286 * \returns true on success or false on failure; call SDL_GetError() for more
287 * information.
288 *
289 * \threadsafety It is safe to call this function from any thread.
290 *
291 * \since This function is available since SDL 3.2.0.
292 *
293 * \sa SDL_GetFloatProperty
294 */
295extern SDL_DECLSPEC bool SDLCALL SDL_SetFloatProperty(SDL_PropertiesID props, const char *name, float value);
296
297/**
298 * Set a boolean property in a group of properties.
299 *
300 * \param props the properties to modify.
301 * \param name the name of the property to modify.
302 * \param value the new value of the property.
303 * \returns true on success or false on failure; call SDL_GetError() for more
304 * information.
305 *
306 * \threadsafety It is safe to call this function from any thread.
307 *
308 * \since This function is available since SDL 3.2.0.
309 *
310 * \sa SDL_GetBooleanProperty
311 */
312extern SDL_DECLSPEC bool SDLCALL SDL_SetBooleanProperty(SDL_PropertiesID props, const char *name, bool value);
313
314/**
315 * Return whether a property exists in a group of properties.
316 *
317 * \param props the properties to query.
318 * \param name the name of the property to query.
319 * \returns true if the property exists, or false if it doesn't.
320 *
321 * \threadsafety It is safe to call this function from any thread.
322 *
323 * \since This function is available since SDL 3.2.0.
324 *
325 * \sa SDL_GetPropertyType
326 */
327extern SDL_DECLSPEC bool SDLCALL SDL_HasProperty(SDL_PropertiesID props, const char *name);
328
329/**
330 * Get the type of a property in a group of properties.
331 *
332 * \param props the properties to query.
333 * \param name the name of the property to query.
334 * \returns the type of the property, or SDL_PROPERTY_TYPE_INVALID if it is
335 * not set.
336 *
337 * \threadsafety It is safe to call this function from any thread.
338 *
339 * \since This function is available since SDL 3.2.0.
340 *
341 * \sa SDL_HasProperty
342 */
343extern SDL_DECLSPEC SDL_PropertyType SDLCALL SDL_GetPropertyType(SDL_PropertiesID props, const char *name);
344
345/**
346 * Get a pointer property from a group of properties.
347 *
348 * By convention, the names of properties that SDL exposes on objects will
349 * start with "SDL.", and properties that SDL uses internally will start with
350 * "SDL.internal.". These should be considered read-only and should not be
351 * modified by applications.
352 *
353 * \param props the properties to query.
354 * \param name the name of the property to query.
355 * \param default_value the default value of the property.
356 * \returns the value of the property, or `default_value` if it is not set or
357 * not a pointer property.
358 *
359 * \threadsafety It is safe to call this function from any thread, although
360 * the data returned is not protected and could potentially be
361 * freed if you call SDL_SetPointerProperty() or
362 * SDL_ClearProperty() on these properties from another thread.
363 * If you need to avoid this, use SDL_LockProperties() and
364 * SDL_UnlockProperties().
365 *
366 * \since This function is available since SDL 3.2.0.
367 *
368 * \sa SDL_GetBooleanProperty
369 * \sa SDL_GetFloatProperty
370 * \sa SDL_GetNumberProperty
371 * \sa SDL_GetPropertyType
372 * \sa SDL_GetStringProperty
373 * \sa SDL_HasProperty
374 * \sa SDL_SetPointerProperty
375 */
376extern SDL_DECLSPEC void * SDLCALL SDL_GetPointerProperty(SDL_PropertiesID props, const char *name, void *default_value);
377
378/**
379 * Get a string property from a group of properties.
380 *
381 * \param props the properties to query.
382 * \param name the name of the property to query.
383 * \param default_value the default value of the property.
384 * \returns the value of the property, or `default_value` if it is not set or
385 * not a string property.
386 *
387 * \threadsafety It is safe to call this function from any thread, although
388 * the data returned is not protected and could potentially be
389 * freed if you call SDL_SetStringProperty() or
390 * SDL_ClearProperty() on these properties from another thread.
391 * If you need to avoid this, use SDL_LockProperties() and
392 * SDL_UnlockProperties().
393 *
394 * \since This function is available since SDL 3.2.0.
395 *
396 * \sa SDL_GetPropertyType
397 * \sa SDL_HasProperty
398 * \sa SDL_SetStringProperty
399 */
400extern SDL_DECLSPEC const char * SDLCALL SDL_GetStringProperty(SDL_PropertiesID props, const char *name, const char *default_value);
401
402/**
403 * Get a number property from a group of properties.
404 *
405 * You can use SDL_GetPropertyType() to query whether the property exists and
406 * is a number property.
407 *
408 * \param props the properties to query.
409 * \param name the name of the property to query.
410 * \param default_value the default value of the property.
411 * \returns the value of the property, or `default_value` if it is not set or
412 * not a number property.
413 *
414 * \threadsafety It is safe to call this function from any thread.
415 *
416 * \since This function is available since SDL 3.2.0.
417 *
418 * \sa SDL_GetPropertyType
419 * \sa SDL_HasProperty
420 * \sa SDL_SetNumberProperty
421 */
422extern SDL_DECLSPEC Sint64 SDLCALL SDL_GetNumberProperty(SDL_PropertiesID props, const char *name, Sint64 default_value);
423
424/**
425 * Get a floating point property from a group of properties.
426 *
427 * You can use SDL_GetPropertyType() to query whether the property exists and
428 * is a floating point property.
429 *
430 * \param props the properties to query.
431 * \param name the name of the property to query.
432 * \param default_value the default value of the property.
433 * \returns the value of the property, or `default_value` if it is not set or
434 * not a float property.
435 *
436 * \threadsafety It is safe to call this function from any thread.
437 *
438 * \since This function is available since SDL 3.2.0.
439 *
440 * \sa SDL_GetPropertyType
441 * \sa SDL_HasProperty
442 * \sa SDL_SetFloatProperty
443 */
444extern SDL_DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, const char *name, float default_value);
445
446/**
447 * Get a boolean property from a group of properties.
448 *
449 * You can use SDL_GetPropertyType() to query whether the property exists and
450 * is a boolean property.
451 *
452 * \param props the properties to query.
453 * \param name the name of the property to query.
454 * \param default_value the default value of the property.
455 * \returns the value of the property, or `default_value` if it is not set or
456 * not a boolean property.
457 *
458 * \threadsafety It is safe to call this function from any thread.
459 *
460 * \since This function is available since SDL 3.2.0.
461 *
462 * \sa SDL_GetPropertyType
463 * \sa SDL_HasProperty
464 * \sa SDL_SetBooleanProperty
465 */
466extern SDL_DECLSPEC bool SDLCALL SDL_GetBooleanProperty(SDL_PropertiesID props, const char *name, bool default_value);
467
468/**
469 * Clear a property from a group of properties.
470 *
471 * \param props the properties to modify.
472 * \param name the name of the property to clear.
473 * \returns true on success or false on failure; call SDL_GetError() for more
474 * information.
475 *
476 * \threadsafety It is safe to call this function from any thread.
477 *
478 * \since This function is available since SDL 3.2.0.
479 */
480extern SDL_DECLSPEC bool SDLCALL SDL_ClearProperty(SDL_PropertiesID props, const char *name);
481
482/**
483 * A callback used to enumerate all the properties in a group of properties.
484 *
485 * This callback is called from SDL_EnumerateProperties(), and is called once
486 * per property in the set.
487 *
488 * \param userdata an app-defined pointer passed to the callback.
489 * \param props the SDL_PropertiesID that is being enumerated.
490 * \param name the next property name in the enumeration.
491 *
492 * \threadsafety SDL_EnumerateProperties holds a lock on `props` during this
493 * callback.
494 *
495 * \since This datatype is available since SDL 3.2.0.
496 *
497 * \sa SDL_EnumerateProperties
498 */
499typedef void (SDLCALL *SDL_EnumeratePropertiesCallback)(void *userdata, SDL_PropertiesID props, const char *name);
500
501/**
502 * Enumerate the properties contained in a group of properties.
503 *
504 * The callback function is called for each property in the group of
505 * properties. The properties are locked during enumeration.
506 *
507 * \param props the properties to query.
508 * \param callback the function to call for each property.
509 * \param userdata a pointer that is passed to `callback`.
510 * \returns true on success or false on failure; call SDL_GetError() for more
511 * information.
512 *
513 * \threadsafety It is safe to call this function from any thread.
514 *
515 * \since This function is available since SDL 3.2.0.
516 */
517extern SDL_DECLSPEC bool SDLCALL SDL_EnumerateProperties(SDL_PropertiesID props, SDL_EnumeratePropertiesCallback callback, void *userdata);
518
519/**
520 * Destroy a group of properties.
521 *
522 * All properties are deleted and their cleanup functions will be called, if
523 * any.
524 *
525 * \param props the properties to destroy.
526 *
527 * \threadsafety This function should not be called while these properties are
528 * locked or other threads might be setting or getting values
529 * from these properties.
530 *
531 * \since This function is available since SDL 3.2.0.
532 *
533 * \sa SDL_CreateProperties
534 */
535extern SDL_DECLSPEC void SDLCALL SDL_DestroyProperties(SDL_PropertiesID props);
536
537/* Ends C function definitions when using C++ */
538#ifdef __cplusplus
539}
540#endif
541#include <SDL3/SDL_close_code.h>
542
543#endif /* SDL_properties_h_ */
544