sdl3_sys/generated/
init.rs

1//! All SDL programs need to initialize the library before starting to work
2//! with it.
3//!
4//! Almost everything can simply call [`SDL_Init()`] near startup, with a handful
5//! of flags to specify subsystems to touch. These are here to make sure SDL
6//! does not even attempt to touch low-level pieces of the operating system
7//! that you don't intend to use. For example, you might be using SDL for video
8//! and input but chose an external library for audio, and in this case you
9//! would just need to leave off the [`SDL_INIT_AUDIO`] flag to make sure that
10//! external library has complete control.
11//!
12//! Most apps, when terminating, should call [`SDL_Quit()`]. This will clean up
13//! (nearly) everything that SDL might have allocated, and crucially, it'll
14//! make sure that the display's resolution is back to what the user expects if
15//! you had previously changed it for your game.
16//!
17//! SDL3 apps are strongly encouraged to call [`SDL_SetAppMetadata()`] at startup
18//! to fill in details about the program. This is completely optional, but it
19//! helps in small ways (we can provide an About dialog box for the macOS menu,
20//! we can name the app in the system's audio mixer, etc). Those that want to
21//! provide a _lot_ of information should look at the more-detailed
22//! [`SDL_SetAppMetadataProperty()`].
23
24use super::stdinc::*;
25
26use super::error::*;
27
28use super::events::*;
29
30/// Initialization flags for [`SDL_Init`] and/or [`SDL_InitSubSystem`]
31///
32/// These are the flags which may be passed to [`SDL_Init()`]. You should specify
33/// the subsystems which you will be using in your application.
34///
35/// ## Availability
36/// This datatype is available since SDL 3.2.0.
37///
38/// ## See also
39/// - [`SDL_Init`]
40/// - [`SDL_Quit`]
41/// - [`SDL_InitSubSystem`]
42/// - [`SDL_QuitSubSystem`]
43/// - [`SDL_WasInit`]
44///
45/// ## Known values (`sdl3-sys`)
46/// | Associated constant | Global constant | Description |
47/// | ------------------- | --------------- | ----------- |
48/// | [`AUDIO`](SDL_InitFlags::AUDIO) | [`SDL_INIT_AUDIO`] | [`SDL_INIT_AUDIO`] implies [`SDL_INIT_EVENTS`] |
49/// | [`VIDEO`](SDL_InitFlags::VIDEO) | [`SDL_INIT_VIDEO`] | [`SDL_INIT_VIDEO`] implies [`SDL_INIT_EVENTS`], should be initialized on the main thread |
50/// | [`JOYSTICK`](SDL_InitFlags::JOYSTICK) | [`SDL_INIT_JOYSTICK`] | [`SDL_INIT_JOYSTICK`] implies [`SDL_INIT_EVENTS`] |
51/// | [`HAPTIC`](SDL_InitFlags::HAPTIC) | [`SDL_INIT_HAPTIC`] | |
52/// | [`GAMEPAD`](SDL_InitFlags::GAMEPAD) | [`SDL_INIT_GAMEPAD`] | [`SDL_INIT_GAMEPAD`] implies [`SDL_INIT_JOYSTICK`] |
53/// | [`EVENTS`](SDL_InitFlags::EVENTS) | [`SDL_INIT_EVENTS`] | |
54/// | [`SENSOR`](SDL_InitFlags::SENSOR) | [`SDL_INIT_SENSOR`] | [`SDL_INIT_SENSOR`] implies [`SDL_INIT_EVENTS`] |
55/// | [`CAMERA`](SDL_InitFlags::CAMERA) | [`SDL_INIT_CAMERA`] | [`SDL_INIT_CAMERA`] implies [`SDL_INIT_EVENTS`] |
56#[repr(transparent)]
57#[derive(Clone, Copy, Default, PartialEq, Eq, Hash)]
58pub struct SDL_InitFlags(pub Uint32);
59
60impl ::core::cmp::PartialEq<Uint32> for SDL_InitFlags {
61    #[inline(always)]
62    fn eq(&self, other: &Uint32) -> bool {
63        &self.0 == other
64    }
65}
66
67impl ::core::cmp::PartialEq<SDL_InitFlags> for Uint32 {
68    #[inline(always)]
69    fn eq(&self, other: &SDL_InitFlags) -> bool {
70        self == &other.0
71    }
72}
73
74impl From<SDL_InitFlags> for Uint32 {
75    #[inline(always)]
76    fn from(value: SDL_InitFlags) -> Self {
77        value.0
78    }
79}
80
81#[cfg(feature = "debug-impls")]
82impl ::core::fmt::Debug for SDL_InitFlags {
83    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
84        let mut first = true;
85        let all_bits = 0;
86        write!(f, "SDL_InitFlags(")?;
87        let all_bits = all_bits | Self::AUDIO.0;
88        if (Self::AUDIO != 0 || self.0 == 0) && *self & Self::AUDIO == Self::AUDIO {
89            if !first {
90                write!(f, " | ")?;
91            }
92            first = false;
93            write!(f, "AUDIO")?;
94        }
95        let all_bits = all_bits | Self::VIDEO.0;
96        if (Self::VIDEO != 0 || self.0 == 0) && *self & Self::VIDEO == Self::VIDEO {
97            if !first {
98                write!(f, " | ")?;
99            }
100            first = false;
101            write!(f, "VIDEO")?;
102        }
103        let all_bits = all_bits | Self::JOYSTICK.0;
104        if (Self::JOYSTICK != 0 || self.0 == 0) && *self & Self::JOYSTICK == Self::JOYSTICK {
105            if !first {
106                write!(f, " | ")?;
107            }
108            first = false;
109            write!(f, "JOYSTICK")?;
110        }
111        let all_bits = all_bits | Self::HAPTIC.0;
112        if (Self::HAPTIC != 0 || self.0 == 0) && *self & Self::HAPTIC == Self::HAPTIC {
113            if !first {
114                write!(f, " | ")?;
115            }
116            first = false;
117            write!(f, "HAPTIC")?;
118        }
119        let all_bits = all_bits | Self::GAMEPAD.0;
120        if (Self::GAMEPAD != 0 || self.0 == 0) && *self & Self::GAMEPAD == Self::GAMEPAD {
121            if !first {
122                write!(f, " | ")?;
123            }
124            first = false;
125            write!(f, "GAMEPAD")?;
126        }
127        let all_bits = all_bits | Self::EVENTS.0;
128        if (Self::EVENTS != 0 || self.0 == 0) && *self & Self::EVENTS == Self::EVENTS {
129            if !first {
130                write!(f, " | ")?;
131            }
132            first = false;
133            write!(f, "EVENTS")?;
134        }
135        let all_bits = all_bits | Self::SENSOR.0;
136        if (Self::SENSOR != 0 || self.0 == 0) && *self & Self::SENSOR == Self::SENSOR {
137            if !first {
138                write!(f, " | ")?;
139            }
140            first = false;
141            write!(f, "SENSOR")?;
142        }
143        let all_bits = all_bits | Self::CAMERA.0;
144        if (Self::CAMERA != 0 || self.0 == 0) && *self & Self::CAMERA == Self::CAMERA {
145            if !first {
146                write!(f, " | ")?;
147            }
148            first = false;
149            write!(f, "CAMERA")?;
150        }
151
152        if self.0 & !all_bits != 0 {
153            if !first {
154                write!(f, " | ")?;
155            }
156            write!(f, "{:#x}", self.0)?;
157        } else if first {
158            write!(f, "0")?;
159        }
160        write!(f, ")")
161    }
162}
163
164impl ::core::ops::BitAnd for SDL_InitFlags {
165    type Output = Self;
166
167    #[inline(always)]
168    fn bitand(self, rhs: Self) -> Self::Output {
169        Self(self.0 & rhs.0)
170    }
171}
172
173impl ::core::ops::BitAndAssign for SDL_InitFlags {
174    #[inline(always)]
175    fn bitand_assign(&mut self, rhs: Self) {
176        self.0 &= rhs.0;
177    }
178}
179
180impl ::core::ops::BitOr for SDL_InitFlags {
181    type Output = Self;
182
183    #[inline(always)]
184    fn bitor(self, rhs: Self) -> Self::Output {
185        Self(self.0 | rhs.0)
186    }
187}
188
189impl ::core::ops::BitOrAssign for SDL_InitFlags {
190    #[inline(always)]
191    fn bitor_assign(&mut self, rhs: Self) {
192        self.0 |= rhs.0;
193    }
194}
195
196impl ::core::ops::BitXor for SDL_InitFlags {
197    type Output = Self;
198
199    #[inline(always)]
200    fn bitxor(self, rhs: Self) -> Self::Output {
201        Self(self.0 ^ rhs.0)
202    }
203}
204
205impl ::core::ops::BitXorAssign for SDL_InitFlags {
206    #[inline(always)]
207    fn bitxor_assign(&mut self, rhs: Self) {
208        self.0 ^= rhs.0;
209    }
210}
211
212impl ::core::ops::Not for SDL_InitFlags {
213    type Output = Self;
214
215    #[inline(always)]
216    fn not(self) -> Self::Output {
217        Self(!self.0)
218    }
219}
220
221impl SDL_InitFlags {
222    /// [`SDL_INIT_AUDIO`] implies [`SDL_INIT_EVENTS`]
223    pub const AUDIO: Self = Self((0x00000010 as Uint32));
224    /// [`SDL_INIT_VIDEO`] implies [`SDL_INIT_EVENTS`], should be initialized on the main thread
225    pub const VIDEO: Self = Self((0x00000020 as Uint32));
226    /// [`SDL_INIT_JOYSTICK`] implies [`SDL_INIT_EVENTS`]
227    pub const JOYSTICK: Self = Self((0x00000200 as Uint32));
228    pub const HAPTIC: Self = Self((0x00001000 as Uint32));
229    /// [`SDL_INIT_GAMEPAD`] implies [`SDL_INIT_JOYSTICK`]
230    pub const GAMEPAD: Self = Self((0x00002000 as Uint32));
231    pub const EVENTS: Self = Self((0x00004000 as Uint32));
232    /// [`SDL_INIT_SENSOR`] implies [`SDL_INIT_EVENTS`]
233    pub const SENSOR: Self = Self((0x00008000 as Uint32));
234    /// [`SDL_INIT_CAMERA`] implies [`SDL_INIT_EVENTS`]
235    pub const CAMERA: Self = Self((0x00010000 as Uint32));
236}
237
238/// [`SDL_INIT_AUDIO`] implies [`SDL_INIT_EVENTS`]
239pub const SDL_INIT_AUDIO: SDL_InitFlags = SDL_InitFlags::AUDIO;
240/// [`SDL_INIT_VIDEO`] implies [`SDL_INIT_EVENTS`], should be initialized on the main thread
241pub const SDL_INIT_VIDEO: SDL_InitFlags = SDL_InitFlags::VIDEO;
242/// [`SDL_INIT_JOYSTICK`] implies [`SDL_INIT_EVENTS`]
243pub const SDL_INIT_JOYSTICK: SDL_InitFlags = SDL_InitFlags::JOYSTICK;
244pub const SDL_INIT_HAPTIC: SDL_InitFlags = SDL_InitFlags::HAPTIC;
245/// [`SDL_INIT_GAMEPAD`] implies [`SDL_INIT_JOYSTICK`]
246pub const SDL_INIT_GAMEPAD: SDL_InitFlags = SDL_InitFlags::GAMEPAD;
247pub const SDL_INIT_EVENTS: SDL_InitFlags = SDL_InitFlags::EVENTS;
248/// [`SDL_INIT_SENSOR`] implies [`SDL_INIT_EVENTS`]
249pub const SDL_INIT_SENSOR: SDL_InitFlags = SDL_InitFlags::SENSOR;
250/// [`SDL_INIT_CAMERA`] implies [`SDL_INIT_EVENTS`]
251pub const SDL_INIT_CAMERA: SDL_InitFlags = SDL_InitFlags::CAMERA;
252
253impl SDL_InitFlags {
254    /// Initialize a `SDL_InitFlags` from a raw value.
255    #[inline(always)]
256    pub const fn new(value: Uint32) -> Self {
257        Self(value)
258    }
259}
260
261impl SDL_InitFlags {
262    /// Get a copy of the inner raw value.
263    #[inline(always)]
264    pub const fn value(&self) -> Uint32 {
265        self.0
266    }
267}
268
269#[cfg(feature = "metadata")]
270impl sdl3_sys::metadata::GroupMetadata for SDL_InitFlags {
271    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
272        &crate::metadata::init::METADATA_SDL_InitFlags;
273}
274
275/// Return values for optional main callbacks.
276///
277/// Returning [`SDL_APP_SUCCESS`] or [`SDL_APP_FAILURE`] from [`SDL_AppInit`],
278/// [`SDL_AppEvent`], or [`SDL_AppIterate`] will terminate the program and report
279/// success/failure to the operating system. What that means is
280/// platform-dependent. On Unix, for example, on success, the process error
281/// code will be zero, and on failure it will be 1. This interface doesn't
282/// allow you to return specific exit codes, just whether there was an error
283/// generally or not.
284///
285/// Returning [`SDL_APP_CONTINUE`] from these functions will let the app continue
286/// to run.
287///
288/// See
289/// [Main callbacks in SDL3](https://wiki.libsdl.org/SDL3/README-main-functions#main-callbacks-in-sdl3)
290/// for complete details.
291///
292/// ## Availability
293/// This enum is available since SDL 3.2.0.
294///
295/// ## Known values (`sdl3-sys`)
296/// | Associated constant | Global constant | Description |
297/// | ------------------- | --------------- | ----------- |
298/// | [`CONTINUE`](SDL_AppResult::CONTINUE) | [`SDL_APP_CONTINUE`] | Value that requests that the app continue from the main callbacks. |
299/// | [`SUCCESS`](SDL_AppResult::SUCCESS) | [`SDL_APP_SUCCESS`] | Value that requests termination with success from the main callbacks. |
300/// | [`FAILURE`](SDL_AppResult::FAILURE) | [`SDL_APP_FAILURE`] | Value that requests termination with error from the main callbacks. |
301#[repr(transparent)]
302#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
303pub struct SDL_AppResult(pub ::core::ffi::c_int);
304
305impl ::core::cmp::PartialEq<::core::ffi::c_int> for SDL_AppResult {
306    #[inline(always)]
307    fn eq(&self, other: &::core::ffi::c_int) -> bool {
308        &self.0 == other
309    }
310}
311
312impl ::core::cmp::PartialEq<SDL_AppResult> for ::core::ffi::c_int {
313    #[inline(always)]
314    fn eq(&self, other: &SDL_AppResult) -> bool {
315        self == &other.0
316    }
317}
318
319impl From<SDL_AppResult> for ::core::ffi::c_int {
320    #[inline(always)]
321    fn from(value: SDL_AppResult) -> Self {
322        value.0
323    }
324}
325
326#[cfg(feature = "debug-impls")]
327impl ::core::fmt::Debug for SDL_AppResult {
328    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
329        #[allow(unreachable_patterns)]
330        f.write_str(match *self {
331            Self::CONTINUE => "SDL_APP_CONTINUE",
332            Self::SUCCESS => "SDL_APP_SUCCESS",
333            Self::FAILURE => "SDL_APP_FAILURE",
334
335            _ => return write!(f, "SDL_AppResult({})", self.0),
336        })
337    }
338}
339
340impl SDL_AppResult {
341    /// Value that requests that the app continue from the main callbacks.
342    pub const CONTINUE: Self = Self((0 as ::core::ffi::c_int));
343    /// Value that requests termination with success from the main callbacks.
344    pub const SUCCESS: Self = Self((1 as ::core::ffi::c_int));
345    /// Value that requests termination with error from the main callbacks.
346    pub const FAILURE: Self = Self((2 as ::core::ffi::c_int));
347}
348
349/// Value that requests that the app continue from the main callbacks.
350pub const SDL_APP_CONTINUE: SDL_AppResult = SDL_AppResult::CONTINUE;
351/// Value that requests termination with success from the main callbacks.
352pub const SDL_APP_SUCCESS: SDL_AppResult = SDL_AppResult::SUCCESS;
353/// Value that requests termination with error from the main callbacks.
354pub const SDL_APP_FAILURE: SDL_AppResult = SDL_AppResult::FAILURE;
355
356impl SDL_AppResult {
357    /// Initialize a `SDL_AppResult` from a raw value.
358    #[inline(always)]
359    pub const fn new(value: ::core::ffi::c_int) -> Self {
360        Self(value)
361    }
362}
363
364impl SDL_AppResult {
365    /// Get a copy of the inner raw value.
366    #[inline(always)]
367    pub const fn value(&self) -> ::core::ffi::c_int {
368        self.0
369    }
370}
371
372#[cfg(feature = "metadata")]
373impl sdl3_sys::metadata::GroupMetadata for SDL_AppResult {
374    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
375        &crate::metadata::init::METADATA_SDL_AppResult;
376}
377
378/// Function pointer typedef for [`SDL_AppInit`].
379///
380/// These are used by [`SDL_EnterAppMainCallbacks`]. This mechanism operates behind
381/// the scenes for apps using the optional main callbacks. Apps that want to
382/// use this should just implement [`SDL_AppInit`] directly.
383///
384/// ## Parameters
385/// - `appstate`: a place where the app can optionally store a pointer for
386///   future use.
387/// - `argc`: the standard ANSI C main's argc; number of elements in `argv`.
388/// - `argv`: the standard ANSI C main's argv; array of command line
389///   arguments.
390///
391/// ## Return value
392/// Returns [`SDL_APP_FAILURE`] to terminate with an error, [`SDL_APP_SUCCESS`] to
393///   terminate with success, [`SDL_APP_CONTINUE`] to continue.
394///
395/// ## Availability
396/// This datatype is available since SDL 3.2.0.
397pub type SDL_AppInit_func = ::core::option::Option<
398    unsafe extern "C" fn(
399        appstate: *mut *mut ::core::ffi::c_void,
400        argc: ::core::ffi::c_int,
401        argv: *mut *mut ::core::ffi::c_char,
402    ) -> SDL_AppResult,
403>;
404
405/// Function pointer typedef for [`SDL_AppIterate`].
406///
407/// These are used by [`SDL_EnterAppMainCallbacks`]. This mechanism operates behind
408/// the scenes for apps using the optional main callbacks. Apps that want to
409/// use this should just implement [`SDL_AppIterate`] directly.
410///
411/// ## Parameters
412/// - `appstate`: an optional pointer, provided by the app in [`SDL_AppInit`].
413///
414/// ## Return value
415/// Returns [`SDL_APP_FAILURE`] to terminate with an error, [`SDL_APP_SUCCESS`] to
416///   terminate with success, [`SDL_APP_CONTINUE`] to continue.
417///
418/// ## Availability
419/// This datatype is available since SDL 3.2.0.
420pub type SDL_AppIterate_func = ::core::option::Option<
421    unsafe extern "C" fn(appstate: *mut ::core::ffi::c_void) -> SDL_AppResult,
422>;
423
424/// Function pointer typedef for [`SDL_AppEvent`].
425///
426/// These are used by [`SDL_EnterAppMainCallbacks`]. This mechanism operates behind
427/// the scenes for apps using the optional main callbacks. Apps that want to
428/// use this should just implement [`SDL_AppEvent`] directly.
429///
430/// ## Parameters
431/// - `appstate`: an optional pointer, provided by the app in [`SDL_AppInit`].
432/// - `event`: the new event for the app to examine.
433///
434/// ## Return value
435/// Returns [`SDL_APP_FAILURE`] to terminate with an error, [`SDL_APP_SUCCESS`] to
436///   terminate with success, [`SDL_APP_CONTINUE`] to continue.
437///
438/// ## Availability
439/// This datatype is available since SDL 3.2.0.
440pub type SDL_AppEvent_func = ::core::option::Option<
441    unsafe extern "C" fn(
442        appstate: *mut ::core::ffi::c_void,
443        event: *mut SDL_Event,
444    ) -> SDL_AppResult,
445>;
446
447/// Function pointer typedef for [`SDL_AppQuit`].
448///
449/// These are used by [`SDL_EnterAppMainCallbacks`]. This mechanism operates behind
450/// the scenes for apps using the optional main callbacks. Apps that want to
451/// use this should just implement [`SDL_AppEvent`] directly.
452///
453/// ## Parameters
454/// - `appstate`: an optional pointer, provided by the app in [`SDL_AppInit`].
455/// - `result`: the result code that terminated the app (success or failure).
456///
457/// ## Availability
458/// This datatype is available since SDL 3.2.0.
459pub type SDL_AppQuit_func = ::core::option::Option<
460    unsafe extern "C" fn(appstate: *mut ::core::ffi::c_void, result: SDL_AppResult),
461>;
462
463unsafe extern "C" {
464    /// Initialize the SDL library.
465    ///
466    /// [`SDL_Init()`] simply forwards to calling [`SDL_InitSubSystem()`]. Therefore, the
467    /// two may be used interchangeably. Though for readability of your code
468    /// [`SDL_InitSubSystem()`] might be preferred.
469    ///
470    /// The file I/O (for example: [`SDL_IOFromFile`]) and threading ([`SDL_CreateThread`])
471    /// subsystems are initialized by default. Message boxes
472    /// ([`SDL_ShowSimpleMessageBox`]) also attempt to work without initializing the
473    /// video subsystem, in hopes of being useful in showing an error dialog when
474    /// [`SDL_Init`] fails. You must specifically initialize other subsystems if you
475    /// use them in your application.
476    ///
477    /// Logging (such as [`SDL_Log`]) works without initialization, too.
478    ///
479    /// `flags` may be any of the following OR'd together:
480    ///
481    /// - [`SDL_INIT_AUDIO`]\: audio subsystem; automatically initializes the events
482    ///   subsystem
483    /// - [`SDL_INIT_VIDEO`]\: video subsystem; automatically initializes the events
484    ///   subsystem, should be initialized on the main thread.
485    /// - [`SDL_INIT_JOYSTICK`]\: joystick subsystem; automatically initializes the
486    ///   events subsystem
487    /// - [`SDL_INIT_HAPTIC`]\: haptic (force feedback) subsystem
488    /// - [`SDL_INIT_GAMEPAD`]\: gamepad subsystem; automatically initializes the
489    ///   joystick subsystem
490    /// - [`SDL_INIT_EVENTS`]\: events subsystem
491    /// - [`SDL_INIT_SENSOR`]\: sensor subsystem; automatically initializes the events
492    ///   subsystem
493    /// - [`SDL_INIT_CAMERA`]\: camera subsystem; automatically initializes the events
494    ///   subsystem
495    ///
496    /// Subsystem initialization is ref-counted, you must call [`SDL_QuitSubSystem()`]
497    /// for each [`SDL_InitSubSystem()`] to correctly shutdown a subsystem manually (or
498    /// call [`SDL_Quit()`] to force shutdown). If a subsystem is already loaded then
499    /// this call will increase the ref-count and return.
500    ///
501    /// Consider reporting some basic metadata about your application before
502    /// calling [`SDL_Init`], using either [`SDL_SetAppMetadata()`] or
503    /// [`SDL_SetAppMetadataProperty()`].
504    ///
505    /// ## Parameters
506    /// - `flags`: subsystem initialization flags.
507    ///
508    /// ## Return value
509    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
510    ///   information.
511    ///
512    /// ## Thread safety
513    /// This function should only be called on the main thread.
514    ///
515    /// ## Availability
516    /// This function is available since SDL 3.2.0.
517    ///
518    /// ## See also
519    /// - [`SDL_SetAppMetadata`]
520    /// - [`SDL_SetAppMetadataProperty`]
521    /// - [`SDL_InitSubSystem`]
522    /// - [`SDL_Quit`]
523    /// - [`SDL_SetMainReady`]
524    /// - [`SDL_WasInit`]
525    pub fn SDL_Init(flags: SDL_InitFlags) -> ::core::primitive::bool;
526}
527
528unsafe extern "C" {
529    /// Compatibility function to initialize the SDL library.
530    ///
531    /// This function and [`SDL_Init()`] are interchangeable.
532    ///
533    /// ## Parameters
534    /// - `flags`: any of the flags used by [`SDL_Init()`]; see [`SDL_Init`] for details.
535    ///
536    /// ## Return value
537    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
538    ///   information.
539    ///
540    /// ## Thread safety
541    /// This function should only be called on the main thread.
542    ///
543    /// ## Availability
544    /// This function is available since SDL 3.2.0.
545    ///
546    /// ## See also
547    /// - [`SDL_Init`]
548    /// - [`SDL_Quit`]
549    /// - [`SDL_QuitSubSystem`]
550    pub fn SDL_InitSubSystem(flags: SDL_InitFlags) -> ::core::primitive::bool;
551}
552
553unsafe extern "C" {
554    /// Shut down specific SDL subsystems.
555    ///
556    /// You still need to call [`SDL_Quit()`] even if you close all open subsystems
557    /// with [`SDL_QuitSubSystem()`].
558    ///
559    /// ## Parameters
560    /// - `flags`: any of the flags used by [`SDL_Init()`]; see [`SDL_Init`] for details.
561    ///
562    /// ## Thread safety
563    /// This function is not thread safe.
564    ///
565    /// ## Availability
566    /// This function is available since SDL 3.2.0.
567    ///
568    /// ## See also
569    /// - [`SDL_InitSubSystem`]
570    /// - [`SDL_Quit`]
571    pub fn SDL_QuitSubSystem(flags: SDL_InitFlags);
572}
573
574unsafe extern "C" {
575    /// Get a mask of the specified subsystems which are currently initialized.
576    ///
577    /// ## Parameters
578    /// - `flags`: any of the flags used by [`SDL_Init()`]; see [`SDL_Init`] for details.
579    ///
580    /// ## Return value
581    /// Returns a mask of all initialized subsystems if `flags` is 0, otherwise it
582    ///   returns the initialization status of the specified subsystems.
583    ///
584    /// ## Thread safety
585    /// This function is not thread safe.
586    ///
587    /// ## Availability
588    /// This function is available since SDL 3.2.0.
589    ///
590    /// ## See also
591    /// - [`SDL_Init`]
592    /// - [`SDL_InitSubSystem`]
593    pub fn SDL_WasInit(flags: SDL_InitFlags) -> SDL_InitFlags;
594}
595
596unsafe extern "C" {
597    /// Clean up all initialized subsystems.
598    ///
599    /// You should call this function even if you have already shutdown each
600    /// initialized subsystem with [`SDL_QuitSubSystem()`]. It is safe to call this
601    /// function even in the case of errors in initialization.
602    ///
603    /// You can use this function with atexit() to ensure that it is run when your
604    /// application is shutdown, but it is not wise to do this from a library or
605    /// other dynamically loaded code.
606    ///
607    /// ## Thread safety
608    /// This function should only be called on the main thread.
609    ///
610    /// ## Availability
611    /// This function is available since SDL 3.2.0.
612    ///
613    /// ## See also
614    /// - [`SDL_Init`]
615    /// - [`SDL_QuitSubSystem`]
616    pub fn SDL_Quit();
617}
618
619unsafe extern "C" {
620    /// Return whether this is the main thread.
621    ///
622    /// On Apple platforms, the main thread is the thread that runs your program's
623    /// main() entry point. On other platforms, the main thread is the one that
624    /// calls SDL_Init([`SDL_INIT_VIDEO`]), which should usually be the one that runs
625    /// your program's main() entry point. If you are using the main callbacks,
626    /// [`SDL_AppInit()`], [`SDL_AppIterate()`], and [`SDL_AppQuit()`] are all called on the
627    /// main thread.
628    ///
629    /// ## Return value
630    /// Returns true if this thread is the main thread, or false otherwise.
631    ///
632    /// ## Thread safety
633    /// It is safe to call this function from any thread.
634    ///
635    /// ## Availability
636    /// This function is available since SDL 3.2.0.
637    ///
638    /// ## See also
639    /// - [`SDL_RunOnMainThread`]
640    pub fn SDL_IsMainThread() -> ::core::primitive::bool;
641}
642
643/// Callback run on the main thread.
644///
645/// ## Parameters
646/// - `userdata`: an app-controlled pointer that is passed to the callback.
647///
648/// ## Availability
649/// This datatype is available since SDL 3.2.0.
650///
651/// ## See also
652/// - [`SDL_RunOnMainThread`]
653pub type SDL_MainThreadCallback =
654    ::core::option::Option<unsafe extern "C" fn(userdata: *mut ::core::ffi::c_void)>;
655
656unsafe extern "C" {
657    /// Call a function on the main thread during event processing.
658    ///
659    /// If this is called on the main thread, the callback is executed immediately.
660    /// If this is called on another thread, this callback is queued for execution
661    /// on the main thread during event processing.
662    ///
663    /// Be careful of deadlocks when using this functionality. You should not have
664    /// the main thread wait for the current thread while this function is being
665    /// called with `wait_complete` true.
666    ///
667    /// ## Parameters
668    /// - `callback`: the callback to call on the main thread.
669    /// - `userdata`: a pointer that is passed to `callback`.
670    /// - `wait_complete`: true to wait for the callback to complete, false to
671    ///   return immediately.
672    ///
673    /// ## Return value
674    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
675    ///   information.
676    ///
677    /// ## Thread safety
678    /// It is safe to call this function from any thread.
679    ///
680    /// ## Availability
681    /// This function is available since SDL 3.2.0.
682    ///
683    /// ## See also
684    /// - [`SDL_IsMainThread`]
685    pub fn SDL_RunOnMainThread(
686        callback: SDL_MainThreadCallback,
687        userdata: *mut ::core::ffi::c_void,
688        wait_complete: ::core::primitive::bool,
689    ) -> ::core::primitive::bool;
690}
691
692unsafe extern "C" {
693    /// Specify basic metadata about your app.
694    ///
695    /// You can optionally provide metadata about your app to SDL. This is not
696    /// required, but strongly encouraged.
697    ///
698    /// There are several locations where SDL can make use of metadata (an "About"
699    /// box in the macOS menu bar, the name of the app can be shown on some audio
700    /// mixers, etc). Any piece of metadata can be left as NULL, if a specific
701    /// detail doesn't make sense for the app.
702    ///
703    /// This function should be called as early as possible, before [`SDL_Init`].
704    /// Multiple calls to this function are allowed, but various state might not
705    /// change once it has been set up with a previous call to this function.
706    ///
707    /// Passing a NULL removes any previous metadata.
708    ///
709    /// This is a simplified interface for the most important information. You can
710    /// supply significantly more detailed metadata with
711    /// [`SDL_SetAppMetadataProperty()`].
712    ///
713    /// ## Parameters
714    /// - `appname`: The name of the application ("My Game 2: Bad Guy's
715    ///   Revenge!").
716    /// - `appversion`: The version of the application ("1.0.0beta5" or a git
717    ///   hash, or whatever makes sense).
718    /// - `appidentifier`: A unique string in reverse-domain format that
719    ///   identifies this app ("com.example.mygame2").
720    ///
721    /// ## Return value
722    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
723    ///   information.
724    ///
725    /// ## Thread safety
726    /// It is safe to call this function from any thread.
727    ///
728    /// ## Availability
729    /// This function is available since SDL 3.2.0.
730    ///
731    /// ## See also
732    /// - [`SDL_SetAppMetadataProperty`]
733    pub fn SDL_SetAppMetadata(
734        appname: *const ::core::ffi::c_char,
735        appversion: *const ::core::ffi::c_char,
736        appidentifier: *const ::core::ffi::c_char,
737    ) -> ::core::primitive::bool;
738}
739
740unsafe extern "C" {
741    /// Specify metadata about your app through a set of properties.
742    ///
743    /// You can optionally provide metadata about your app to SDL. This is not
744    /// required, but strongly encouraged.
745    ///
746    /// There are several locations where SDL can make use of metadata (an "About"
747    /// box in the macOS menu bar, the name of the app can be shown on some audio
748    /// mixers, etc). Any piece of metadata can be left out, if a specific detail
749    /// doesn't make sense for the app.
750    ///
751    /// This function should be called as early as possible, before [`SDL_Init`].
752    /// Multiple calls to this function are allowed, but various state might not
753    /// change once it has been set up with a previous call to this function.
754    ///
755    /// Once set, this metadata can be read using [`SDL_GetAppMetadataProperty()`].
756    ///
757    /// These are the supported properties:
758    ///
759    /// - [`SDL_PROP_APP_METADATA_NAME_STRING`]\: The human-readable name of the
760    ///   application, like "My Game 2: Bad Guy's Revenge!". This will show up
761    ///   anywhere the OS shows the name of the application separately from window
762    ///   titles, such as volume control applets, etc. This defaults to "SDL
763    ///   Application".
764    /// - [`SDL_PROP_APP_METADATA_VERSION_STRING`]\: The version of the app that is
765    ///   running; there are no rules on format, so "1.0.3beta2" and "April 22nd,
766    ///   2024" and a git hash are all valid options. This has no default.
767    /// - [`SDL_PROP_APP_METADATA_IDENTIFIER_STRING`]\: A unique string that
768    ///   identifies this app. This must be in reverse-domain format, like
769    ///   "com.example.mygame2". This string is used by desktop compositors to
770    ///   identify and group windows together, as well as match applications with
771    ///   associated desktop settings and icons. If you plan to package your
772    ///   application in a container such as Flatpak, the app ID should match the
773    ///   name of your Flatpak container as well. This has no default.
774    /// - [`SDL_PROP_APP_METADATA_CREATOR_STRING`]\: The human-readable name of the
775    ///   creator/developer/maker of this app, like "MojoWorkshop, LLC"
776    /// - [`SDL_PROP_APP_METADATA_COPYRIGHT_STRING`]\: The human-readable copyright
777    ///   notice, like "Copyright (c) 2024 MojoWorkshop, LLC" or whatnot. Keep this
778    ///   to one line, don't paste a copy of a whole software license in here. This
779    ///   has no default.
780    /// - [`SDL_PROP_APP_METADATA_URL_STRING`]\: A URL to the app on the web. Maybe a
781    ///   product page, or a storefront, or even a GitHub repository, for user's
782    ///   further information This has no default.
783    /// - [`SDL_PROP_APP_METADATA_TYPE_STRING`]\: The type of application this is.
784    ///   Currently this string can be "game" for a video game, "mediaplayer" for a
785    ///   media player, or generically "application" if nothing else applies.
786    ///   Future versions of SDL might add new types. This defaults to
787    ///   "application".
788    ///
789    /// ## Parameters
790    /// - `name`: the name of the metadata property to set.
791    /// - `value`: the value of the property, or NULL to remove that property.
792    ///
793    /// ## Return value
794    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
795    ///   information.
796    ///
797    /// ## Thread safety
798    /// It is safe to call this function from any thread.
799    ///
800    /// ## Availability
801    /// This function is available since SDL 3.2.0.
802    ///
803    /// ## See also
804    /// - [`SDL_GetAppMetadataProperty`]
805    /// - [`SDL_SetAppMetadata`]
806    pub fn SDL_SetAppMetadataProperty(
807        name: *const ::core::ffi::c_char,
808        value: *const ::core::ffi::c_char,
809    ) -> ::core::primitive::bool;
810}
811
812pub const SDL_PROP_APP_METADATA_NAME_STRING: *const ::core::ffi::c_char =
813    c"SDL.app.metadata.name".as_ptr();
814
815pub const SDL_PROP_APP_METADATA_VERSION_STRING: *const ::core::ffi::c_char =
816    c"SDL.app.metadata.version".as_ptr();
817
818pub const SDL_PROP_APP_METADATA_IDENTIFIER_STRING: *const ::core::ffi::c_char =
819    c"SDL.app.metadata.identifier".as_ptr();
820
821pub const SDL_PROP_APP_METADATA_CREATOR_STRING: *const ::core::ffi::c_char =
822    c"SDL.app.metadata.creator".as_ptr();
823
824pub const SDL_PROP_APP_METADATA_COPYRIGHT_STRING: *const ::core::ffi::c_char =
825    c"SDL.app.metadata.copyright".as_ptr();
826
827pub const SDL_PROP_APP_METADATA_URL_STRING: *const ::core::ffi::c_char =
828    c"SDL.app.metadata.url".as_ptr();
829
830pub const SDL_PROP_APP_METADATA_TYPE_STRING: *const ::core::ffi::c_char =
831    c"SDL.app.metadata.type".as_ptr();
832
833unsafe extern "C" {
834    /// Get metadata about your app.
835    ///
836    /// This returns metadata previously set using [`SDL_SetAppMetadata()`] or
837    /// [`SDL_SetAppMetadataProperty()`]. See [`SDL_SetAppMetadataProperty()`] for the list
838    /// of available properties and their meanings.
839    ///
840    /// ## Parameters
841    /// - `name`: the name of the metadata property to get.
842    ///
843    /// ## Return value
844    /// Returns the current value of the metadata property, or the default if it
845    ///   is not set, NULL for properties with no default.
846    ///
847    /// ## Thread safety
848    /// It is safe to call this function from any thread, although
849    ///   the string returned is not protected and could potentially be
850    ///   freed if you call [`SDL_SetAppMetadataProperty()`] to set that
851    ///   property from another thread.
852    ///
853    /// ## Availability
854    /// This function is available since SDL 3.2.0.
855    ///
856    /// ## See also
857    /// - [`SDL_SetAppMetadata`]
858    /// - [`SDL_SetAppMetadataProperty`]
859    pub fn SDL_GetAppMetadataProperty(
860        name: *const ::core::ffi::c_char,
861    ) -> *const ::core::ffi::c_char;
862}
863
864#[cfg(doc)]
865use crate::everything::*;
sdl3_sys/generated/init.rs

sdl3_sys/generated/
init.rs
