SDL 1.3 API proposal: power status

SDL Development
1

I noticed that Steam’s overlay, when running on a laptop, could report
my system’s battery status in-game, which is useful, since the Windows
system tray icon that I would normally rely on isn’t visible when
playing full screen.

I could also imagine scenarios where a game might want to reduce
framerate or detail when not on AC power, in order to reduce the power
burned when it is a limited resource.

So I added an API to SDL 1.3 to report power status.

Usage is fairly simple…

 int seconds, percent;
 const SDL_PowerState state = SDL_GetPowerInfo(&seconds, &percent);

…“state” tells you where the system is getting power:

  • Unknown (no power management support in the library or OS, or error).
  • From a battery
  • From AC power, solely.
  • From AC power, charging a battery.
  • From AC power, with a fully-charged battery.

For cases where a battery exists, “seconds” will be the (perhaps wildly
incorrect) estimate of seconds of battery life remaining (or -1 if we
couldn’t guess), and percent is a number from 0 to 100, representing
percentage of battery life left (or -1 if we don’t know). No battery in
the system will produce -1 for both of these values, too.

I’ve filled in implementations for Windows (should support all Win32,
Win64, and WinCE/PocketPC platforms), Linux (just /proc/apm at the
moment, but /proc/acpi and /sys/power are easy enough to fill in), Mac
OS X, and OS/2.

Presumably the Mac stuff will work on iPhone, and Nintendo DS has a stub
implementation for now (apparently you get this information through the
ARM7, and I don’t know the voodoo magic for that).

The file test/testpower.c in the patch is an example program.

I’ve only tested (or even compiled) this patch on Mac OS X. I’m looking
for comments before I commit it, including “my god man, please don’t
commit this!”

Patch attached.

–ryan.

-------------- next part --------------
An embedded and charset-unspecified text was scrubbed…
Name: SDL13-power-RYAN1.diff
URL: http://lists.libsdl.org/pipermail/sdl-libsdl.org/attachments/20090606/314b3817/attachment.txt

2

This sounds like a good idea, but I want to warn people who may use
this API. Always give the user some control over whatever effect the
power state induces. Maybe it’s just a problem with KPowersave rather
than the underlying system, but on my Macbook, it has always acted
strangely. Most of the time it reports an empty battery no matter the
true state. Before I adjusted the settings, it responded to this
critical battery situation by shutting down the computer… Not quite
good.

Jonny D

3

Awesome. :slight_smile: I’ve often stared at Tux Paint running full-screen, and
thought that a clock in the lower right corner might be useful.
Power status for laptops would be, as well!

-bill!On Sat, Jun 06, 2009 at 03:04:17AM -0400, Ryan C. Gordon wrote:

So I added an API to SDL 1.3 to report power status.

4

Awesome. :slight_smile: I’ve often stared at Tux Paint running full-screen, and
thought that a clock in the lower right corner might be useful.
Power status for laptops would be, as well!

It’s in Subversion now, revision #4538.

I still need to fill in the Linux code, and I need someone else to
handle Nintendo DS (and iPhone?). If this fails to build somewhere,
please let me know!

–ryan.

5

Don’t forget about PSP :slight_smile:

2009/6/7 Ryan C. Gordon >

Awesome. :slight_smile: I’ve often stared at Tux Paint running full-screen, and

thought that a clock in the lower right corner might be useful.
Power status for laptops would be, as well!

It’s in Subversion now, revision #4538.

I still need to fill in the Linux code, and I need someone else to handle
Nintendo DS (and iPhone?). If this fails to build somewhere, please let me
know!

–ryan.

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

6

Ryan C. Gordon skrev:

Usage is fairly simple…

int seconds, percent;
const SDL_PowerState state = SDL_GetPowerInfo(&seconds, &percent);

This makes me wonder how seconds and percent can be negative? On which
platform does that ever happen? Have you really checked it?

7

seconds and percent become -1 if the info is not available or the function
encountered an error.

2009/6/7 Erik > Ryan C. Gordon skrev:

Usage is fairly simple…

int seconds, percent;
const SDL_PowerState state = SDL_GetPowerInfo(&seconds, &percent);

This makes me wonder how seconds and percent can be negative? On which
platform does that ever happen? Have you really checked it?

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

8

Hello !

I noticed that Steam’s overlay, when running on a laptop, could report
my system’s battery status in-game, which is useful, since the Windows
system tray icon that I would normally rely on isn’t visible when
playing full screen.

I could also imagine scenarios where a game might want to reduce
framerate or detail when not on AC power, in order to reduce the power
burned when it is a limited resource.

So I added an API to SDL 1.3 to report power status.

Usage is fairly simple…

int seconds, percent;
const SDL_PowerState state = SDL_GetPowerInfo(&seconds, &percent);

…“state” tells you where the system is getting power:

  • Unknown (no power management support in the library or OS, or error).
  • From a battery
  • From AC power, solely.
  • From AC power, charging a battery.
  • From AC power, with a fully-charged battery.

For cases where a battery exists, “seconds” will be the (perhaps wildly
incorrect) estimate of seconds of battery life remaining (or -1 if we
couldn’t guess), and percent is a number from 0 to 100, representing
percentage of battery life left (or -1 if we don’t know). No battery in
the system will produce -1 for both of these values, too.

This is a great idea, as portable devices like iPhone,
Nintendo DS and Sony PSP are getting more important every day.

CU

9

Out of curiosity, when you create a game for DS or PSP, is the
battery display not available? (Either on-screen, or as its
own LED light, like on the Atari Lynx or GameBoy Advance?)

I know on cellphone platforms I’ve used, the annunciator bar
at the top (signal strength, battery status, etc.) is usually
something you cannot get rid of. Your app doesn’t even know
about that zone of the display.On Sun, Jun 07, 2009 at 11:53:33AM +0200, Torsten Giebl wrote:

This is a great idea, as portable devices like iPhone,
Nintendo DS and Sony PSP are getting more important every day.

–
-bill!
Sent from my computer

10

Not all of them, unfortunately. I have a Motorola Q phone (about
the suckiest smartphone ever, but I got it free from work, so…)
and it displays the battery indicator in the normal screen area,
and thus only on the “desktop” screen.>----- Original Message ----

From: Bill Kendrick
Subject: Re: [SDL] SDL 1.3 API proposal: power status

On Sun, Jun 07, 2009 at 11:53:33AM +0200, Torsten Giebl wrote:

This is a great idea, as portable devices like iPhone,
Nintendo DS and Sony PSP are getting more important every day.

Out of curiosity, when you create a game for DS or PSP, is the
battery display not available? (Either on-screen, or as its
own LED light, like on the Atari Lynx or GameBoy Advance?)

I know on cellphone platforms I’ve used, the annunciator bar
at the top (signal strength, battery status, etc.) is usually
something you cannot get rid of. Your app doesn’t even know
about that zone of the display.

–
-bill!
Sent from my computer

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

11

This makes me wonder how seconds and percent can be negative? On which
platform does that ever happen? Have you really checked it?

Some platforms and hardware can’t tell you time-to-empty (/proc/acpi on
Linux), some know there is a battery, but not its current state (any
platform, if you ask at the right moment).

Things that are hardwired (and never have a battery, like a desktop, or
don’t have a battery system at all, like a dreamcast) will return -1
here, just to report a sane value.

–ryan.

12

I know on cellphone platforms I’ve used, the annunciator bar
at the top (signal strength, battery status, etc.) is usually
something you cannot get rid of. Your app doesn’t even know
about that zone of the display.

iPhone games can overwrite the battery display.

–ryan.

13

On PSP you can check battery by pressing HOME button, but it won’t tell you
EXACTLY how much time is left or pecent of batterry. However, this
information IS available (some plugins use it, look CWCheat) and can be used
in this extension.

2009/6/7 Ryan C. Gordon >

I know on cellphone platforms I’ve used, the annunciator bar

at the top (signal strength, battery status, etc.) is usually
something you cannot get rid of. Your app doesn’t even know
about that zone of the display.

iPhone games can overwrite the battery display.

–ryan.

SDL mailing list
SDL at lists.libsdl.org
http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org

14

I still need to fill in the Linux code, and I need someone else to
handle Nintendo DS (and iPhone?). If this fails to build somewhere,
please let me know!

As an update, I have tested this on Linux (/proc/acpi and /proc/apm),
Mac OS X, and Windows, and updated the project files to support it.

I would appreciate if someone could poke at this on iPhone, Windows CE,
and Nintendo DS, as I can’t implement these platforms myself.

All interested parties should give it a try on their machines for the
standard platforms (try testpower.c in the “test” directory). Please let
me know if it got the information wrong, etc.

If your platform needs tweaking and you want to tweak:

  • Possibly implement src/power/MY_PLATFORM/SDL_syspower.c
  • Possibly update the list of drivers at the top of src/power/SDL_power.c
  • Define SDL_POWER_MY_PLATFORM as appropriate.
  • Add src/power/SDL_power.c and src/power/MY_PLATFORM/SDL_syspower.c to
    the build.

The code for platforms like BeOS and OS/2 is in revision control, but I
can’t test these to even see if they compile…heck, at the moment, I
don’t think we even support these platforms in SDL 1.3, but I filled
them in, just in case.

Comments, questions, problems: please see me.

Thanks,
–ryan.