sdl3_sys/generated/
power.rs

1//! SDL power management routines.
2//!
3//! There is a single function in this category: [`SDL_GetPowerInfo()`].
4//!
5//! This function is useful for games on the go. This allows an app to know if
6//! it's running on a draining battery, which can be useful if the app wants to
7//! reduce processing, or perhaps framerate, to extend the duration of the
8//! battery's charge. Perhaps the app just wants to show a battery meter when
9//! fullscreen, or alert the user when the power is getting extremely low, so
10//! they can save their game.
11
12use super::stdinc::*;
13
14use super::error::*;
15
16/// The basic state for the system's power supply.
17///
18/// These are results returned by [`SDL_GetPowerInfo()`].
19///
20/// ## Availability
21/// This enum is available since SDL 3.2.0.
22///
23/// ## Known values (`sdl3-sys`)
24/// | Associated constant | Global constant | Description |
25/// | ------------------- | --------------- | ----------- |
26/// | [`ERROR`](SDL_PowerState::ERROR) | [`SDL_POWERSTATE_ERROR`] | error determining power status |
27/// | [`UNKNOWN`](SDL_PowerState::UNKNOWN) | [`SDL_POWERSTATE_UNKNOWN`] | cannot determine power status |
28/// | [`ON_BATTERY`](SDL_PowerState::ON_BATTERY) | [`SDL_POWERSTATE_ON_BATTERY`] | Not plugged in, running on the battery |
29/// | [`NO_BATTERY`](SDL_PowerState::NO_BATTERY) | [`SDL_POWERSTATE_NO_BATTERY`] | Plugged in, no battery available |
30/// | [`CHARGING`](SDL_PowerState::CHARGING) | [`SDL_POWERSTATE_CHARGING`] | Plugged in, charging battery |
31/// | [`CHARGED`](SDL_PowerState::CHARGED) | [`SDL_POWERSTATE_CHARGED`] | Plugged in, battery charged |
32#[repr(transparent)]
33#[derive(Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
34pub struct SDL_PowerState(pub ::core::ffi::c_int);
35
36impl ::core::cmp::PartialEq<::core::ffi::c_int> for SDL_PowerState {
37    #[inline(always)]
38    fn eq(&self, other: &::core::ffi::c_int) -> bool {
39        &self.0 == other
40    }
41}
42
43impl ::core::cmp::PartialEq<SDL_PowerState> for ::core::ffi::c_int {
44    #[inline(always)]
45    fn eq(&self, other: &SDL_PowerState) -> bool {
46        self == &other.0
47    }
48}
49
50impl From<SDL_PowerState> for ::core::ffi::c_int {
51    #[inline(always)]
52    fn from(value: SDL_PowerState) -> Self {
53        value.0
54    }
55}
56
57#[cfg(feature = "debug-impls")]
58impl ::core::fmt::Debug for SDL_PowerState {
59    fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
60        #[allow(unreachable_patterns)]
61        f.write_str(match *self {
62            Self::ERROR => "SDL_POWERSTATE_ERROR",
63            Self::UNKNOWN => "SDL_POWERSTATE_UNKNOWN",
64            Self::ON_BATTERY => "SDL_POWERSTATE_ON_BATTERY",
65            Self::NO_BATTERY => "SDL_POWERSTATE_NO_BATTERY",
66            Self::CHARGING => "SDL_POWERSTATE_CHARGING",
67            Self::CHARGED => "SDL_POWERSTATE_CHARGED",
68
69            _ => return write!(f, "SDL_PowerState({})", self.0),
70        })
71    }
72}
73
74impl SDL_PowerState {
75    /// error determining power status
76    pub const ERROR: Self = Self((-1_i32 as ::core::ffi::c_int));
77    /// cannot determine power status
78    pub const UNKNOWN: Self = Self((0_i32 as ::core::ffi::c_int));
79    /// Not plugged in, running on the battery
80    pub const ON_BATTERY: Self = Self((1_i32 as ::core::ffi::c_int));
81    /// Plugged in, no battery available
82    pub const NO_BATTERY: Self = Self((2_i32 as ::core::ffi::c_int));
83    /// Plugged in, charging battery
84    pub const CHARGING: Self = Self((3_i32 as ::core::ffi::c_int));
85    /// Plugged in, battery charged
86    pub const CHARGED: Self = Self((4_i32 as ::core::ffi::c_int));
87}
88
89/// error determining power status
90pub const SDL_POWERSTATE_ERROR: SDL_PowerState = SDL_PowerState::ERROR;
91/// cannot determine power status
92pub const SDL_POWERSTATE_UNKNOWN: SDL_PowerState = SDL_PowerState::UNKNOWN;
93/// Not plugged in, running on the battery
94pub const SDL_POWERSTATE_ON_BATTERY: SDL_PowerState = SDL_PowerState::ON_BATTERY;
95/// Plugged in, no battery available
96pub const SDL_POWERSTATE_NO_BATTERY: SDL_PowerState = SDL_PowerState::NO_BATTERY;
97/// Plugged in, charging battery
98pub const SDL_POWERSTATE_CHARGING: SDL_PowerState = SDL_PowerState::CHARGING;
99/// Plugged in, battery charged
100pub const SDL_POWERSTATE_CHARGED: SDL_PowerState = SDL_PowerState::CHARGED;
101
102#[cfg(feature = "metadata")]
103impl sdl3_sys::metadata::GroupMetadata for SDL_PowerState {
104    const GROUP_METADATA: &'static sdl3_sys::metadata::Group =
105        &crate::metadata::power::METADATA_SDL_PowerState;
106}
107
108unsafe extern "C" {
109    /// Get the current power supply details.
110    ///
111    /// You should never take a battery status as absolute truth. Batteries
112    /// (especially failing batteries) are delicate hardware, and the values
113    /// reported here are best estimates based on what that hardware reports. It's
114    /// not uncommon for older batteries to lose stored power much faster than it
115    /// reports, or completely drain when reporting it has 20 percent left, etc.
116    ///
117    /// Battery status can change at any time; if you are concerned with power
118    /// state, you should call this function frequently, and perhaps ignore changes
119    /// until they seem to be stable for a few seconds.
120    ///
121    /// It's possible a platform can only report battery percentage or time left
122    /// but not both.
123    ///
124    /// On some platforms, retrieving power supply details might be expensive. If
125    /// you want to display continuous status you could call this function every
126    /// minute or so.
127    ///
128    /// ## Parameters
129    /// - `seconds`: a pointer filled in with the seconds of battery life left,
130    ///   or NULL to ignore. This will be filled in with -1 if we
131    ///   can't determine a value or there is no battery.
132    /// - `percent`: a pointer filled in with the percentage of battery life
133    ///   left, between 0 and 100, or NULL to ignore. This will be
134    ///   filled in with -1 when we can't determine a value or there
135    ///   is no battery.
136    ///
137    /// ## Return value
138    /// Returns the current battery state or [`SDL_POWERSTATE_ERROR`] on failure;
139    ///   call [`SDL_GetError()`] for more information.
140    ///
141    /// ## Availability
142    /// This function is available since SDL 3.2.0.
143    pub fn SDL_GetPowerInfo(
144        seconds: *mut ::core::ffi::c_int,
145        percent: *mut ::core::ffi::c_int,
146    ) -> SDL_PowerState;
147}
148
149#[cfg(doc)]
150use crate::everything::*;
sdl3_sys/generated/power.rs

sdl3_sys/generated/
power.rs
