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