Mobility
Use the Intel Mobile Platform SDK to Retrieve and Track Changes to the 'Power' and 'Display' Context at Runtime.
By Rajshree Chabukswar
As the industry moves toward more mobile platforms, the ability of an application to determine power status and scale display capabilities accordingly to save power is becoming more important. With the evolution of mobile platforms, battery life becomes as critical as performance; therefore, applications need to have a way of keeping track of available battery life and be enabled to handle transitions from external (AC) to internal (battery) power sources. Systems would also benefit from being able to scale display richness based on available battery life.
The Intel® Mobile Platform Software Development Kit (Intel® Mobile Platform SDK) provides a common framework for application developers to retrieve properties of “Power” and “Display” status along with a way to track changes to these at runtime. This paper demonstrates how to use the Intel® Mobile Platform SDK to extract Power and Display information. Sample code written in C++, using DirectX* for Microsoft Windows* XP, is also included. The sample application here is based on the Microsoft DirectX (summer 2004) BasicHSLS sample.
The architecture and design of the Intel Mobile Platform SDK will allow implementation of the following†:
Currently Supported:
Architectures:
Operating Systems:
Languages:
Runtime Environment:
† Not all capabilities are currently supported.
The GUI of the sample application is shown below. The spheres bounce between the walls of the cube and from each other using a collision detection and resolution algorithm. The number of spheres in the scene and the rate at which the next position is computed can be adjusted by using slider control on the right in the UI.
Figure 1: Sample application UI
Figure 1 displays a screen-shot of when the application is running on an external power source (running on AC power). Note that setting the threshold for a low battery alert is available only when running on battery power. The user can select the battery level at which they prefer to be notified using the slider control and select the check-box below to activate it. Once the specified battery level is reached, the display screen state is set to “blanked” and the application state is frozen. The display screen resolution is lowered when switching from AC to battery power.
The context layer provided by the Intel Mobile Platform SDK enables an application to discover, manipulate, and interact with the system context such as Power and “Connectivity,” without knowledge of the specific devices that provide context and resource information.
Power: The Power interface in the context layer hides the complexity of requiring enumerating all batteries on the system and provides a more general view of power-related condition and events. The application can use this information to alter its behavior when the system is running on an internal power source vs. an external power source. In this sample application, the resolution of the display changes as a result of changes in power source.
Display: Mobile devices come in a variety of form factors, for example, PDAs, laptops, and mobile phones. Cross-platform applications must be aware of the geometry and orientation of the display in order to optimize its UI. In this sample application, the display properties are changed based on a system running on external vs. internal power as well as when a specified low-threshold battery life is reached.
The Intel Mobile Platform SDK provides several APIs and properties to retrieve information from contexts such as Power and Display. Below is an overview of those used in the sample application.
Initialization
Power and Display context are initialized as shown below. Refer to the code in “BasicPhysics.CPP” to get details on variable definitions.
//Initialize PowerInstance i.e. powerInstance powerInstance= dynamic_cast<PowerInstance*>(capClass.GetInstance(L"Power")); //Initialize DisplayAdapterInstance i.e. pMyDisplayAdapterInstance pMyDisplayAdapterCollection= (DisplayAdapterCollection*)dispClass.GetInstances(); pMyDisplayAdapterInstance= (DisplayAdapterInstance*)pMyDisplayAdapterCollection->Next();
Once the objects are initialized, the properties of each of these can be retrieved as shown below.
‘Power/Display’ Properties and APIs
The Intel Mobile Platform SDK provides access to multiple APIs and properties. To see complete list, refer to the “Programmer's Guide” provided with the Intel Mobile Platform SDK.
One of the important properties provided by Power context is that it will retrieve information about the system power source, whether it is internal or external. The sample application uses this property to change application behavior based on the current power source.
if (!powerInstance->Source.IsNull())
{
if (powerInstance->Source.GetValue() == SourceEnum::Internal)
{
// Running on Battery
}
else
{
// Running on AC
}
}
Similarly, the Display context provides properties to retrieve the resolution of the current display. In this application, the Display resolution is changed based on if the system is running on external vs. internal power.
//Get current Horizontal and Vertical resolution values //and store in OrigHorizRes and OrigVerRes from //pMyDisplayAdapterInstance OrigHorizRes = pMyDisplayAdapterInstance->HorizontalResolution.GetValue(); OrigVerRes = pMyDisplayAdapterInstance->VerticalResolution.GetValue();
In the sample application, the original display resolution is retrieved during application initialization so when the application exits, the resolution can be restored to the original values.
Event Notification
Event notification is the mechanism by which changes occurring in the system are tracked and the appropriate action is taken at runtime as they occur. If the power source is changed during an application run, the application should be able to see these changes without polling and take action appropriately. An application must register all relevant events for the item for which notification is to be received.
To receive notification of a change in power source, this application registers for both 'InternallyPowered' and 'ExternallyPowered'.
//Add Observers to appropriate properties to track changes from //AC/Battery power source powerInstance->InternallyPowered.AddObserver(source); powerInstance->ExternallyPowered.AddObserver(source);
Where “source” is an object of an “Observer” class.
An Observer class is an abstract base class provided by the Intel Mobile Platform SDK. Developers can derive and implement their own observer class by providing implementation for the “Notify()” method as shown below.
In this application, the Notify() method changes the Display resolution whenever the power source is changed. For example, when the power source is changed to “Internal,” the screen resolution is set to 800x600.
class PowerSource : public Observer
{
public:
void Notify(const Event& e)
{
try
{
switch (e.GetType())
{
case Event::eInternallyPowered:
//Change display mode to lower resolution
//800x600 using SetDisplayMode
DisplayMode NewDispMode;
NewDispMode.HorizontalResolution = 800;
NewDispMode.VerticalResolution = 600;
NewDispMode.ColorDepth= pMyDisplayAdapterInstance->ColorDepth.GetValue();
NewDispMode.RefreshRate= pMyDisplayAdapterInstance->RefreshRate.GetValue();
pMyDisplayAdapterInstance->SetDisplayMode(NewDispMode);
break;
case Event::eExternallyPowered:
// Re-set the display mode to original resolution
DisplayMode dispMode;
dispMode.HorizontalResolution = OrigHorizRes;
dispMode.VerticalResolution = OrigVerRes;
dispMode.ColorDepth= pMyDisplayAdapterInstance->ColorDepth.GetValue();
dispMode.RefreshRate= pMyDisplayAdapterInstance->RefreshRate.GetValue();
pMyDisplayAdapterInstance->SetDisplayMode(dispMode);
break;
}
}
catch (IntelMobileException& ex)
{
}
}
};
Thresholds
Another way to track changes to system context is by using “Thresholds.” Thresholds create events when specified conditions are met. To be notified of a threshold, an object of Threshold type needs to be created as shown below.
UIntGaugeThreshold LowThreshold; //Set Property for observation LowThreshold.SetObservedProperty(powerInstance->PercentRemaining); //Set Low, High Threshold values and granularity period LowThreshold.SetLowThreshold(power_level); LowThreshold.SetHighThreshold(power_level+5); LowThreshold.SetGranularityPeriod(5000); //Add observer to gauge object LowThreshold.AddObserver(powerStat); //Start executing gauge object LowThreshold.Start();
powerStat is an object of the “PowerStatus” observer class and it is defined as shown below. When the specified low battery life is reached, this class will set display screen state to “Blanked.”
class PowerStatus : public Observer
{
public:
void Notify(const Event& e)
{
try
{
if (e.GetType() == Event::eThresholdLow)
{
//Set ScreenState to Blanked when low power is //reached
pMyDisplayAdapterInstance->ScreenState.SetValue(ScreenStateEnum::Blanked);
LowThreshold.Stop();
}
}
catch (IntelMobileException& ex)
{
}
}
};
It is also important to remove the observer to make sure that no hanging references remain when the application exits.
powerInstance->InternallyPowered.RemoveObserver(source); powerInstance->ExternallyPowered.RemoveObserver(source); LowThreshold.RemoveObserver(powerStat);
The sample discussed here demonstrates how to use the Intel Mobile Platform SDK to retrieve and track changes to the Power and Display context at runtime. As shown in the sample, system information is easily accessible using the Intel Mobile Platform SDK. Developers can also access device-specific information such as “Battery,” “Network Adapters,” “Processor,” and others, including “Bandwidth” and “Connectivity.”
For more information visit: Intel Mobile Platform SDK