|
1
|
1 /*
|
|
|
2 Simple DirectMedia Layer
|
|
|
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
|
|
|
4
|
|
|
5 This software is provided 'as-is', without any express or implied
|
|
|
6 warranty. In no event will the authors be held liable for any damages
|
|
|
7 arising from the use of this software.
|
|
|
8
|
|
|
9 Permission is granted to anyone to use this software for any purpose,
|
|
|
10 including commercial applications, and to alter it and redistribute it
|
|
|
11 freely, subject to the following restrictions:
|
|
|
12
|
|
|
13 1. The origin of this software must not be misrepresented; you must not
|
|
|
14 claim that you wrote the original software. If you use this software
|
|
|
15 in a product, an acknowledgment in the product documentation would be
|
|
|
16 appreciated but is not required.
|
|
|
17 2. Altered source versions must be plainly marked as such, and must not be
|
|
|
18 misrepresented as being the original software.
|
|
|
19 3. This notice may not be removed or altered from any source distribution.
|
|
|
20 */
|
|
|
21
|
|
|
22 #ifndef SDL_power_h_
|
|
|
23 #define SDL_power_h_
|
|
|
24
|
|
|
25 /**
|
|
|
26 * # CategoryPower
|
|
|
27 *
|
|
|
28 * SDL power management routines.
|
|
|
29 *
|
|
|
30 * There is a single function in this category: SDL_GetPowerInfo().
|
|
|
31 *
|
|
|
32 * This function is useful for games on the go. This allows an app to know if
|
|
|
33 * it's running on a draining battery, which can be useful if the app wants to
|
|
|
34 * reduce processing, or perhaps framerate, to extend the duration of the
|
|
|
35 * battery's charge. Perhaps the app just wants to show a battery meter when
|
|
|
36 * fullscreen, or alert the user when the power is getting extremely low, so
|
|
|
37 * they can save their game.
|
|
|
38 */
|
|
|
39
|
|
|
40 #include <SDL3/SDL_stdinc.h>
|
|
|
41 #include <SDL3/SDL_error.h>
|
|
|
42
|
|
|
43 #include <SDL3/SDL_begin_code.h>
|
|
|
44 /* Set up for C function definitions, even when using C++ */
|
|
|
45 #ifdef __cplusplus
|
|
|
46 extern "C" {
|
|
|
47 #endif
|
|
|
48
|
|
|
49 /**
|
|
|
50 * The basic state for the system's power supply.
|
|
|
51 *
|
|
|
52 * These are results returned by SDL_GetPowerInfo().
|
|
|
53 *
|
|
|
54 * \since This enum is available since SDL 3.2.0.
|
|
|
55 */
|
|
|
56 typedef enum SDL_PowerState
|
|
|
57 {
|
|
|
58 SDL_POWERSTATE_ERROR = -1, /**< error determining power status */
|
|
|
59 SDL_POWERSTATE_UNKNOWN, /**< cannot determine power status */
|
|
|
60 SDL_POWERSTATE_ON_BATTERY, /**< Not plugged in, running on the battery */
|
|
|
61 SDL_POWERSTATE_NO_BATTERY, /**< Plugged in, no battery available */
|
|
|
62 SDL_POWERSTATE_CHARGING, /**< Plugged in, charging battery */
|
|
|
63 SDL_POWERSTATE_CHARGED /**< Plugged in, battery charged */
|
|
|
64 } SDL_PowerState;
|
|
|
65
|
|
|
66 /**
|
|
|
67 * Get the current power supply details.
|
|
|
68 *
|
|
|
69 * You should never take a battery status as absolute truth. Batteries
|
|
|
70 * (especially failing batteries) are delicate hardware, and the values
|
|
|
71 * reported here are best estimates based on what that hardware reports. It's
|
|
|
72 * not uncommon for older batteries to lose stored power much faster than it
|
|
|
73 * reports, or completely drain when reporting it has 20 percent left, etc.
|
|
|
74 *
|
|
|
75 * Battery status can change at any time; if you are concerned with power
|
|
|
76 * state, you should call this function frequently, and perhaps ignore changes
|
|
|
77 * until they seem to be stable for a few seconds.
|
|
|
78 *
|
|
|
79 * It's possible a platform can only report battery percentage or time left
|
|
|
80 * but not both.
|
|
|
81 *
|
|
|
82 * On some platforms, retrieving power supply details might be expensive. If
|
|
|
83 * you want to display continuous status you could call this function every
|
|
|
84 * minute or so.
|
|
|
85 *
|
|
|
86 * \param seconds a pointer filled in with the seconds of battery life left,
|
|
|
87 * or NULL to ignore. This will be filled in with -1 if we
|
|
|
88 * can't determine a value or there is no battery.
|
|
|
89 * \param percent a pointer filled in with the percentage of battery life
|
|
|
90 * left, between 0 and 100, or NULL to ignore. This will be
|
|
|
91 * filled in with -1 when we can't determine a value or there
|
|
|
92 * is no battery.
|
|
|
93 * \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure;
|
|
|
94 * call SDL_GetError() for more information.
|
|
|
95 *
|
|
|
96 * \since This function is available since SDL 3.2.0.
|
|
|
97 */
|
|
|
98 extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *seconds, int *percent);
|
|
|
99
|
|
|
100 /* Ends C function definitions when using C++ */
|
|
|
101 #ifdef __cplusplus
|
|
|
102 }
|
|
|
103 #endif
|
|
|
104 #include <SDL3/SDL_close_code.h>
|
|
|
105
|
|
|
106 #endif /* SDL_power_h_ */
|
