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
253#[cfg(feature = "metadata")]
254impl sdl3_sys::metadata::GroupMetadata for SDL_InitFlags {
255    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
256        &crate::metadata::init::METADATA_SDL_InitFlags;
257}
258
259/// Return values for optional main callbacks.
260///
261/// Returning [`SDL_APP_SUCCESS`] or [`SDL_APP_FAILURE`] from [`SDL_AppInit`],
262/// [`SDL_AppEvent`], or [`SDL_AppIterate`] will terminate the program and report
263/// success/failure to the operating system. What that means is
264/// platform-dependent. On Unix, for example, on success, the process error
265/// code will be zero, and on failure it will be 1. This interface doesn't
266/// allow you to return specific exit codes, just whether there was an error
267/// generally or not.
268///
269/// Returning [`SDL_APP_CONTINUE`] from these functions will let the app continue
270/// to run.
271///
272/// See
273/// [Main callbacks in SDL3](https://wiki.libsdl.org/SDL3/README-main-functions#main-callbacks-in-sdl3)
274/// for complete details.
275///
276/// ## Availability
277/// This enum is available since SDL 3.2.0.
278///
279/// ## Known values (`sdl3-sys`)
280/// | Associated constant | Global constant | Description |
281/// | ------------------- | --------------- | ----------- |
282/// | [`CONTINUE`](SDL_AppResult::CONTINUE) | [`SDL_APP_CONTINUE`] | Value that requests that the app continue from the main callbacks. |
283/// | [`SUCCESS`](SDL_AppResult::SUCCESS) | [`SDL_APP_SUCCESS`] | Value that requests termination with success from the main callbacks. |
284/// | [`FAILURE`](SDL_AppResult::FAILURE) | [`SDL_APP_FAILURE`] | Value that requests termination with error from the main callbacks. |
285#[repr(transparent)]
286#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
287pub struct SDL_AppResult(pub ::core::ffi::c_int);
288
289impl ::core::cmp::PartialEq<::core::ffi::c_int> for SDL_AppResult {
290    #[inline(always)]
291    fn eq(&self, other: &::core::ffi::c_int) -> bool {
292        &self.0 == other
293    }
294}
295
296impl ::core::cmp::PartialEq<SDL_AppResult> for ::core::ffi::c_int {
297    #[inline(always)]
298    fn eq(&self, other: &SDL_AppResult) -> bool {
299        self == &other.0
300    }
301}
302
303impl From<SDL_AppResult> for ::core::ffi::c_int {
304    #[inline(always)]
305    fn from(value: SDL_AppResult) -> Self {
306        value.0
307    }
308}
309
310#[cfg(feature = "debug-impls")]
311impl ::core::fmt::Debug for SDL_AppResult {
312    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
313        #[allow(unreachable_patterns)]
314        f.write_str(match *self {
315            Self::CONTINUE => "SDL_APP_CONTINUE",
316            Self::SUCCESS => "SDL_APP_SUCCESS",
317            Self::FAILURE => "SDL_APP_FAILURE",
318
319            _ => return write!(f, "SDL_AppResult({})", self.0),
320        })
321    }
322}
323
324impl SDL_AppResult {
325    /// Value that requests that the app continue from the main callbacks.
326    pub const CONTINUE: Self = Self((0 as ::core::ffi::c_int));
327    /// Value that requests termination with success from the main callbacks.
328    pub const SUCCESS: Self = Self((1 as ::core::ffi::c_int));
329    /// Value that requests termination with error from the main callbacks.
330    pub const FAILURE: Self = Self((2 as ::core::ffi::c_int));
331}
332
333/// Value that requests that the app continue from the main callbacks.
334pub const SDL_APP_CONTINUE: SDL_AppResult = SDL_AppResult::CONTINUE;
335/// Value that requests termination with success from the main callbacks.
336pub const SDL_APP_SUCCESS: SDL_AppResult = SDL_AppResult::SUCCESS;
337/// Value that requests termination with error from the main callbacks.
338pub const SDL_APP_FAILURE: SDL_AppResult = SDL_AppResult::FAILURE;
339
340#[cfg(feature = "metadata")]
341impl sdl3_sys::metadata::GroupMetadata for SDL_AppResult {
342    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
343        &crate::metadata::init::METADATA_SDL_AppResult;
344}
345
346/// Function pointer typedef for [`SDL_AppInit`].
347///
348/// These are used by [`SDL_EnterAppMainCallbacks`]. This mechanism operates behind
349/// the scenes for apps using the optional main callbacks. Apps that want to
350/// use this should just implement [`SDL_AppInit`] directly.
351///
352/// ## Parameters
353/// - `appstate`: a place where the app can optionally store a pointer for
354///   future use.
355/// - `argc`: the standard ANSI C main's argc; number of elements in `argv`.
356/// - `argv`: the standard ANSI C main's argv; array of command line
357///   arguments.
358///
359/// ## Return value
360/// Returns [`SDL_APP_FAILURE`] to terminate with an error, [`SDL_APP_SUCCESS`] to
361///   terminate with success, [`SDL_APP_CONTINUE`] to continue.
362///
363/// ## Availability
364/// This datatype is available since SDL 3.2.0.
365pub type SDL_AppInit_func = ::core::option::Option<
366    unsafe extern "C" fn(
367        appstate: *mut *mut ::core::ffi::c_void,
368        argc: ::core::ffi::c_int,
369        argv: *mut *mut ::core::ffi::c_char,
370    ) -> SDL_AppResult,
371>;
372
373/// Function pointer typedef for [`SDL_AppIterate`].
374///
375/// These are used by [`SDL_EnterAppMainCallbacks`]. This mechanism operates behind
376/// the scenes for apps using the optional main callbacks. Apps that want to
377/// use this should just implement [`SDL_AppIterate`] directly.
378///
379/// ## Parameters
380/// - `appstate`: an optional pointer, provided by the app in [`SDL_AppInit`].
381///
382/// ## Return value
383/// Returns [`SDL_APP_FAILURE`] to terminate with an error, [`SDL_APP_SUCCESS`] to
384///   terminate with success, [`SDL_APP_CONTINUE`] to continue.
385///
386/// ## Availability
387/// This datatype is available since SDL 3.2.0.
388pub type SDL_AppIterate_func = ::core::option::Option<
389    unsafe extern "C" fn(appstate: *mut ::core::ffi::c_void) -> SDL_AppResult,
390>;
391
392/// Function pointer typedef for [`SDL_AppEvent`].
393///
394/// These are used by [`SDL_EnterAppMainCallbacks`]. This mechanism operates behind
395/// the scenes for apps using the optional main callbacks. Apps that want to
396/// use this should just implement [`SDL_AppEvent`] directly.
397///
398/// ## Parameters
399/// - `appstate`: an optional pointer, provided by the app in [`SDL_AppInit`].
400/// - `event`: the new event for the app to examine.
401///
402/// ## Return value
403/// Returns [`SDL_APP_FAILURE`] to terminate with an error, [`SDL_APP_SUCCESS`] to
404///   terminate with success, [`SDL_APP_CONTINUE`] to continue.
405///
406/// ## Availability
407/// This datatype is available since SDL 3.2.0.
408pub type SDL_AppEvent_func = ::core::option::Option<
409    unsafe extern "C" fn(
410        appstate: *mut ::core::ffi::c_void,
411        event: *mut SDL_Event,
412    ) -> SDL_AppResult,
413>;
414
415/// Function pointer typedef for [`SDL_AppQuit`].
416///
417/// These are used by [`SDL_EnterAppMainCallbacks`]. This mechanism operates behind
418/// the scenes for apps using the optional main callbacks. Apps that want to
419/// use this should just implement [`SDL_AppEvent`] directly.
420///
421/// ## Parameters
422/// - `appstate`: an optional pointer, provided by the app in [`SDL_AppInit`].
423/// - `result`: the result code that terminated the app (success or failure).
424///
425/// ## Availability
426/// This datatype is available since SDL 3.2.0.
427pub type SDL_AppQuit_func = ::core::option::Option<
428    unsafe extern "C" fn(appstate: *mut ::core::ffi::c_void, result: SDL_AppResult),
429>;
430
431unsafe extern "C" {
432    /// Initialize the SDL library.
433    ///
434    /// [`SDL_Init()`] simply forwards to calling [`SDL_InitSubSystem()`]. Therefore, the
435    /// two may be used interchangeably. Though for readability of your code
436    /// [`SDL_InitSubSystem()`] might be preferred.
437    ///
438    /// The file I/O (for example: [`SDL_IOFromFile`]) and threading ([`SDL_CreateThread`])
439    /// subsystems are initialized by default. Message boxes
440    /// ([`SDL_ShowSimpleMessageBox`]) also attempt to work without initializing the
441    /// video subsystem, in hopes of being useful in showing an error dialog when
442    /// [`SDL_Init`] fails. You must specifically initialize other subsystems if you
443    /// use them in your application.
444    ///
445    /// Logging (such as [`SDL_Log`]) works without initialization, too.
446    ///
447    /// `flags` may be any of the following OR'd together:
448    ///
449    /// - [`SDL_INIT_AUDIO`]\: audio subsystem; automatically initializes the events
450    ///   subsystem
451    /// - [`SDL_INIT_VIDEO`]\: video subsystem; automatically initializes the events
452    ///   subsystem, should be initialized on the main thread.
453    /// - [`SDL_INIT_JOYSTICK`]\: joystick subsystem; automatically initializes the
454    ///   events subsystem
455    /// - [`SDL_INIT_HAPTIC`]\: haptic (force feedback) subsystem
456    /// - [`SDL_INIT_GAMEPAD`]\: gamepad subsystem; automatically initializes the
457    ///   joystick subsystem
458    /// - [`SDL_INIT_EVENTS`]\: events subsystem
459    /// - [`SDL_INIT_SENSOR`]\: sensor subsystem; automatically initializes the events
460    ///   subsystem
461    /// - [`SDL_INIT_CAMERA`]\: camera subsystem; automatically initializes the events
462    ///   subsystem
463    ///
464    /// Subsystem initialization is ref-counted, you must call [`SDL_QuitSubSystem()`]
465    /// for each [`SDL_InitSubSystem()`] to correctly shutdown a subsystem manually (or
466    /// call [`SDL_Quit()`] to force shutdown). If a subsystem is already loaded then
467    /// this call will increase the ref-count and return.
468    ///
469    /// Consider reporting some basic metadata about your application before
470    /// calling [`SDL_Init`], using either [`SDL_SetAppMetadata()`] or
471    /// [`SDL_SetAppMetadataProperty()`].
472    ///
473    /// ## Parameters
474    /// - `flags`: subsystem initialization flags.
475    ///
476    /// ## Return value
477    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
478    ///   information.
479    ///
480    /// ## Availability
481    /// This function is available since SDL 3.2.0.
482    ///
483    /// ## See also
484    /// - [`SDL_SetAppMetadata`]
485    /// - [`SDL_SetAppMetadataProperty`]
486    /// - [`SDL_InitSubSystem`]
487    /// - [`SDL_Quit`]
488    /// - [`SDL_SetMainReady`]
489    /// - [`SDL_WasInit`]
490    pub fn SDL_Init(flags: SDL_InitFlags) -> ::core::primitive::bool;
491}
492
493unsafe extern "C" {
494    /// Compatibility function to initialize the SDL library.
495    ///
496    /// This function and [`SDL_Init()`] are interchangeable.
497    ///
498    /// ## Parameters
499    /// - `flags`: any of the flags used by [`SDL_Init()`]; see [`SDL_Init`] for details.
500    ///
501    /// ## Return value
502    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
503    ///   information.
504    ///
505    /// ## Availability
506    /// This function is available since SDL 3.2.0.
507    ///
508    /// ## See also
509    /// - [`SDL_Init`]
510    /// - [`SDL_Quit`]
511    /// - [`SDL_QuitSubSystem`]
512    pub fn SDL_InitSubSystem(flags: SDL_InitFlags) -> ::core::primitive::bool;
513}
514
515unsafe extern "C" {
516    /// Shut down specific SDL subsystems.
517    ///
518    /// You still need to call [`SDL_Quit()`] even if you close all open subsystems
519    /// with [`SDL_QuitSubSystem()`].
520    ///
521    /// ## Parameters
522    /// - `flags`: any of the flags used by [`SDL_Init()`]; see [`SDL_Init`] for details.
523    ///
524    /// ## Availability
525    /// This function is available since SDL 3.2.0.
526    ///
527    /// ## See also
528    /// - [`SDL_InitSubSystem`]
529    /// - [`SDL_Quit`]
530    pub fn SDL_QuitSubSystem(flags: SDL_InitFlags);
531}
532
533unsafe extern "C" {
534    /// Get a mask of the specified subsystems which are currently initialized.
535    ///
536    /// ## Parameters
537    /// - `flags`: any of the flags used by [`SDL_Init()`]; see [`SDL_Init`] for details.
538    ///
539    /// ## Return value
540    /// Returns a mask of all initialized subsystems if `flags` is 0, otherwise it
541    ///   returns the initialization status of the specified subsystems.
542    ///
543    /// ## Availability
544    /// This function is available since SDL 3.2.0.
545    ///
546    /// ## See also
547    /// - [`SDL_Init`]
548    /// - [`SDL_InitSubSystem`]
549    pub fn SDL_WasInit(flags: SDL_InitFlags) -> SDL_InitFlags;
550}
551
552unsafe extern "C" {
553    /// Clean up all initialized subsystems.
554    ///
555    /// You should call this function even if you have already shutdown each
556    /// initialized subsystem with [`SDL_QuitSubSystem()`]. It is safe to call this
557    /// function even in the case of errors in initialization.
558    ///
559    /// You can use this function with atexit() to ensure that it is run when your
560    /// application is shutdown, but it is not wise to do this from a library or
561    /// other dynamically loaded code.
562    ///
563    /// ## Availability
564    /// This function is available since SDL 3.2.0.
565    ///
566    /// ## See also
567    /// - [`SDL_Init`]
568    /// - [`SDL_QuitSubSystem`]
569    pub fn SDL_Quit();
570}
571
572unsafe extern "C" {
573    /// Return whether this is the main thread.
574    ///
575    /// On Apple platforms, the main thread is the thread that runs your program's
576    /// main() entry point. On other platforms, the main thread is the one that
577    /// calls SDL_Init([`SDL_INIT_VIDEO`]), which should usually be the one that runs
578    /// your program's main() entry point. If you are using the main callbacks,
579    /// [`SDL_AppInit()`], [`SDL_AppIterate()`], and [`SDL_AppQuit()`] are all called on the
580    /// main thread.
581    ///
582    /// ## Return value
583    /// Returns true if this thread is the main thread, or false otherwise.
584    ///
585    /// ## Thread safety
586    /// It is safe to call this function from any thread.
587    ///
588    /// ## Availability
589    /// This function is available since SDL 3.2.0.
590    ///
591    /// ## See also
592    /// - [`SDL_RunOnMainThread`]
593    pub fn SDL_IsMainThread() -> ::core::primitive::bool;
594}
595
596/// Callback run on the main thread.
597///
598/// ## Parameters
599/// - `userdata`: an app-controlled pointer that is passed to the callback.
600///
601/// ## Availability
602/// This datatype is available since SDL 3.2.0.
603///
604/// ## See also
605/// - [`SDL_RunOnMainThread`]
606pub type SDL_MainThreadCallback =
607    ::core::option::Option<unsafe extern "C" fn(userdata: *mut ::core::ffi::c_void)>;
608
609unsafe extern "C" {
610    /// Call a function on the main thread during event processing.
611    ///
612    /// If this is called on the main thread, the callback is executed immediately.
613    /// If this is called on another thread, this callback is queued for execution
614    /// on the main thread during event processing.
615    ///
616    /// Be careful of deadlocks when using this functionality. You should not have
617    /// the main thread wait for the current thread while this function is being
618    /// called with `wait_complete` true.
619    ///
620    /// ## Parameters
621    /// - `callback`: the callback to call on the main thread.
622    /// - `userdata`: a pointer that is passed to `callback`.
623    /// - `wait_complete`: true to wait for the callback to complete, false to
624    ///   return immediately.
625    ///
626    /// ## Return value
627    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
628    ///   information.
629    ///
630    /// ## Thread safety
631    /// It is safe to call this function from any thread.
632    ///
633    /// ## Availability
634    /// This function is available since SDL 3.2.0.
635    ///
636    /// ## See also
637    /// - [`SDL_IsMainThread`]
638    pub fn SDL_RunOnMainThread(
639        callback: SDL_MainThreadCallback,
640        userdata: *mut ::core::ffi::c_void,
641        wait_complete: ::core::primitive::bool,
642    ) -> ::core::primitive::bool;
643}
644
645unsafe extern "C" {
646    /// Specify basic metadata about your app.
647    ///
648    /// You can optionally provide metadata about your app to SDL. This is not
649    /// required, but strongly encouraged.
650    ///
651    /// There are several locations where SDL can make use of metadata (an "About"
652    /// box in the macOS menu bar, the name of the app can be shown on some audio
653    /// mixers, etc). Any piece of metadata can be left as NULL, if a specific
654    /// detail doesn't make sense for the app.
655    ///
656    /// This function should be called as early as possible, before [`SDL_Init`].
657    /// Multiple calls to this function are allowed, but various state might not
658    /// change once it has been set up with a previous call to this function.
659    ///
660    /// Passing a NULL removes any previous metadata.
661    ///
662    /// This is a simplified interface for the most important information. You can
663    /// supply significantly more detailed metadata with
664    /// [`SDL_SetAppMetadataProperty()`].
665    ///
666    /// ## Parameters
667    /// - `appname`: The name of the application ("My Game 2: Bad Guy's
668    ///   Revenge!").
669    /// - `appversion`: The version of the application ("1.0.0beta5" or a git
670    ///   hash, or whatever makes sense).
671    /// - `appidentifier`: A unique string in reverse-domain format that
672    ///   identifies this app ("com.example.mygame2").
673    ///
674    /// ## Return value
675    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
676    ///   information.
677    ///
678    /// ## Thread safety
679    /// It is safe to call this function from any thread.
680    ///
681    /// ## Availability
682    /// This function is available since SDL 3.2.0.
683    ///
684    /// ## See also
685    /// - [`SDL_SetAppMetadataProperty`]
686    pub fn SDL_SetAppMetadata(
687        appname: *const ::core::ffi::c_char,
688        appversion: *const ::core::ffi::c_char,
689        appidentifier: *const ::core::ffi::c_char,
690    ) -> ::core::primitive::bool;
691}
692
693unsafe extern "C" {
694    /// Specify metadata about your app through a set of properties.
695    ///
696    /// You can optionally provide metadata about your app to SDL. This is not
697    /// required, but strongly encouraged.
698    ///
699    /// There are several locations where SDL can make use of metadata (an "About"
700    /// box in the macOS menu bar, the name of the app can be shown on some audio
701    /// mixers, etc). Any piece of metadata can be left out, if a specific detail
702    /// doesn't make sense for the app.
703    ///
704    /// This function should be called as early as possible, before [`SDL_Init`].
705    /// Multiple calls to this function are allowed, but various state might not
706    /// change once it has been set up with a previous call to this function.
707    ///
708    /// Once set, this metadata can be read using [`SDL_GetAppMetadataProperty()`].
709    ///
710    /// These are the supported properties:
711    ///
712    /// - [`SDL_PROP_APP_METADATA_NAME_STRING`]\: The human-readable name of the
713    ///   application, like "My Game 2: Bad Guy's Revenge!". This will show up
714    ///   anywhere the OS shows the name of the application separately from window
715    ///   titles, such as volume control applets, etc. This defaults to "SDL
716    ///   Application".
717    /// - [`SDL_PROP_APP_METADATA_VERSION_STRING`]\: The version of the app that is
718    ///   running; there are no rules on format, so "1.0.3beta2" and "April 22nd,
719    ///   2024" and a git hash are all valid options. This has no default.
720    /// - [`SDL_PROP_APP_METADATA_IDENTIFIER_STRING`]\: A unique string that
721    ///   identifies this app. This must be in reverse-domain format, like
722    ///   "com.example.mygame2". This string is used by desktop compositors to
723    ///   identify and group windows together, as well as match applications with
724    ///   associated desktop settings and icons. If you plan to package your
725    ///   application in a container such as Flatpak, the app ID should match the
726    ///   name of your Flatpak container as well. This has no default.
727    /// - [`SDL_PROP_APP_METADATA_CREATOR_STRING`]\: The human-readable name of the
728    ///   creator/developer/maker of this app, like "MojoWorkshop, LLC"
729    /// - [`SDL_PROP_APP_METADATA_COPYRIGHT_STRING`]\: The human-readable copyright
730    ///   notice, like "Copyright (c) 2024 MojoWorkshop, LLC" or whatnot. Keep this
731    ///   to one line, don't paste a copy of a whole software license in here. This
732    ///   has no default.
733    /// - [`SDL_PROP_APP_METADATA_URL_STRING`]\: A URL to the app on the web. Maybe a
734    ///   product page, or a storefront, or even a GitHub repository, for user's
735    ///   further information This has no default.
736    /// - [`SDL_PROP_APP_METADATA_TYPE_STRING`]\: The type of application this is.
737    ///   Currently this string can be "game" for a video game, "mediaplayer" for a
738    ///   media player, or generically "application" if nothing else applies.
739    ///   Future versions of SDL might add new types. This defaults to
740    ///   "application".
741    ///
742    /// ## Parameters
743    /// - `name`: the name of the metadata property to set.
744    /// - `value`: the value of the property, or NULL to remove that property.
745    ///
746    /// ## Return value
747    /// Returns true on success or false on failure; call [`SDL_GetError()`] for more
748    ///   information.
749    ///
750    /// ## Thread safety
751    /// It is safe to call this function from any thread.
752    ///
753    /// ## Availability
754    /// This function is available since SDL 3.2.0.
755    ///
756    /// ## See also
757    /// - [`SDL_GetAppMetadataProperty`]
758    /// - [`SDL_SetAppMetadata`]
759    pub fn SDL_SetAppMetadataProperty(
760        name: *const ::core::ffi::c_char,
761        value: *const ::core::ffi::c_char,
762    ) -> ::core::primitive::bool;
763}
764
765pub const SDL_PROP_APP_METADATA_NAME_STRING: *const ::core::ffi::c_char =
766    c"SDL.app.metadata.name".as_ptr();
767
768pub const SDL_PROP_APP_METADATA_VERSION_STRING: *const ::core::ffi::c_char =
769    c"SDL.app.metadata.version".as_ptr();
770
771pub const SDL_PROP_APP_METADATA_IDENTIFIER_STRING: *const ::core::ffi::c_char =
772    c"SDL.app.metadata.identifier".as_ptr();
773
774pub const SDL_PROP_APP_METADATA_CREATOR_STRING: *const ::core::ffi::c_char =
775    c"SDL.app.metadata.creator".as_ptr();
776
777pub const SDL_PROP_APP_METADATA_COPYRIGHT_STRING: *const ::core::ffi::c_char =
778    c"SDL.app.metadata.copyright".as_ptr();
779
780pub const SDL_PROP_APP_METADATA_URL_STRING: *const ::core::ffi::c_char =
781    c"SDL.app.metadata.url".as_ptr();
782
783pub const SDL_PROP_APP_METADATA_TYPE_STRING: *const ::core::ffi::c_char =
784    c"SDL.app.metadata.type".as_ptr();
785
786unsafe extern "C" {
787    /// Get metadata about your app.
788    ///
789    /// This returns metadata previously set using [`SDL_SetAppMetadata()`] or
790    /// [`SDL_SetAppMetadataProperty()`]. See [`SDL_SetAppMetadataProperty()`] for the list
791    /// of available properties and their meanings.
792    ///
793    /// ## Parameters
794    /// - `name`: the name of the metadata property to get.
795    ///
796    /// ## Return value
797    /// Returns the current value of the metadata property, or the default if it
798    ///   is not set, NULL for properties with no default.
799    ///
800    /// ## Thread safety
801    /// It is safe to call this function from any thread, although
802    ///   the string returned is not protected and could potentially be
803    ///   freed if you call [`SDL_SetAppMetadataProperty()`] to set that
804    ///   property from another thread.
805    ///
806    /// ## Availability
807    /// This function is available since SDL 3.2.0.
808    ///
809    /// ## See also
810    /// - [`SDL_SetAppMetadata`]
811    /// - [`SDL_SetAppMetadataProperty`]
812    pub fn SDL_GetAppMetadataProperty(
813        name: *const ::core::ffi::c_char,
814    ) -> *const ::core::ffi::c_char;
815}
816
817#[cfg(doc)]
818use crate::everything::*;
sdl3_sys/generated/init.rs

sdl3_sys/generated/
init.rs
