sdl.properties source code

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