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 | * \param seconds a pointer filled in with the seconds of battery life left, |
83 | * or NULL to ignore. This will be filled in with -1 if we |
84 | * can't determine a value or there is no battery. |
85 | * \param percent a pointer filled in with the percentage of battery life |
86 | * left, between 0 and 100, or NULL to ignore. This will be |
87 | * filled in with -1 we can't determine a value or there is no |
88 | * battery. |
89 | * \returns the current battery state or `SDL_POWERSTATE_ERROR` on failure; |
90 | * call SDL_GetError() for more information. |
91 | * |
92 | * \since This function is available since SDL 3.2.0. |
93 | */ |
94 | extern SDL_DECLSPEC SDL_PowerState SDLCALL SDL_GetPowerInfo(int *seconds, int *percent); |
95 | |
96 | /* Ends C function definitions when using C++ */ |
97 | #ifdef __cplusplus |
98 | } |
99 | #endif |
100 | #include <SDL3/SDL_close_code.h> |
101 | |
102 | #endif /* SDL_power_h_ */ |
103 | |