Backlight

The backlight is controlled independently from the display driver, with one exception: If the registry settings for backlight GPIO and display GPIO are identical, a change of the backlight will also change the state of the display driver accordingly. Please refer to Display driver registry settings for details.

Automatic Backlight Control

By default, the backlight is turned off after a timeout that starts whenever there is no user activity on the system. It is automatically turned on as soon as there is any user activity detected.

The backlight timeout can be controlled manually from the control panel:

Control Panel -> Display

These settings are stored in the registry at key name:

[HKCU\ControlPanel\Backlight]
ACTimeout     =dword:0x00000258      ;Time[seconds] before Backlight is turned off when on external power
BatteryTimeout=dword:0x00000258      ;Time[seconds] before Backlight is turned off when on battery power

.


In order to completely avoid the backlight from turning off, the following registry settings need to be added:

; never turn off backlight
[HKCU\ControlPanel\Backlight]
UseExt            =dword:0x00000000   ; 0: don't switch off backlight when on external power
UseBattery        =dword:0x00000000   ; 0: don't switch off backlight when on battery power

.

Note: On IMX6 image this feature is supported only on release 1.3b4 or newer and is disabled by default, set "UseExt" and "UseBattery" entries to 1 to enable it.

Controlling the Backlight From Your Application

Colibri PXA

You can use the ExtEscape() function to control the backlight from your application, overriding the automatic user activity / timeout detection. The code below shows the basic structure of a call to ExtEscape(). The function sets the backlight status to the value new_backlight, and returns the backlight status before applying the change in old_backlight.

DWORD old_backlight;
DWORD new_backlight=0;
ExtEscape(GetDC(NULL), BACKLIGHT, 4, (char*)&new_backlight, 4, (char*)&old_backlight);

The following values for new_backlight are supported:

• (NULL) Read the current backlight status
• 0 Turn the backlight off before the timer expires
• 255 Turn the backlight on and reset the timer, without any user activity
• 256 Force the backlight off, then ignore timers and user activity
• 511 Force the backlight on, then ignore timers and user activity

The code snipplet below shows how to use the ExtEscape() function:

#define ESCAPECODEBASE          100000
#define MOUSECURSOR             (ESCAPECODEBASE + 20)
#define BACKLIGHT               (ESCAPECODEBASE + 21)
#define BACKLIGHT_FORCE_STATE    256
 
DWORD old_backlight;
DWORD new_backlight=0;
 
 
//Get Backlight Status
ExtEscape(GetDC(NULL), BACKLIGHT, 0, NULL, 4, (char*)&old_backlight);
 
//Disable Backlight until user activity
new_backlight=0;
ExtEscape(GetDC(NULL), BACKLIGHT, 4, (char*)&new_backlight, 4, (char*)&old_backlight);
 
//Enable Backlight until timeout
new_backlight=255;
ExtEscape(GetDC(NULL), BACKLIGHT, 4, (char*)&new_backlight, 4, (char*)&old_backlight);
 
//Force Backlight OFF
new_backlight=0|BACKLIGHT_FORCE_STATE ;
ExtEscape(GetDC(NULL), BACKLIGHT, 4, (char*)&new_backlight, 4, (char*)&old_backlight);
 
//Force Backlight ON
new_backlight=255|BACKLIGHT_FORCE_STATE ;
ExtEscape(GetDC(NULL), BACKLIGHT, 4, (char*)&new_backlight, 4, (char*)&old_backlight);

All modules

The following code runs on all Colibri and Apalis modules

DWORD batteryTimeout;
DWORD acTimeout;
DWORD temp;
DWORD  cbData; 
HKEY  hKey;
DWORD type = REG_DWORD;
HANDLE ev;
 
// Force Backlight OFF
// Backup current backlight timeouts
RegOpenKeyEx(HKEY_CURRENT_USER, L"ControlPanel\\Backlight", 0, KEY_ALL_ACCESS, &hKey);
RegQueryValueEx(hKey, L"BatteryTimeout", NULL, &type, (LPBYTE)&batteryTimeout, &cbData);
RegQueryValueEx(hKey, L"ACTimeout", NULL, &type, (LPBYTE)&acTimeout, &cbData);
// set BL timeout to 0 sec 
RegSetValueEx(hKey, L"BatteryTimeout", 0, REG_DWORD, (LPBYTE)&temp, 4);
RegSetValueEx(hKey, L"ACTimeout", 0, REG_DWORD, (LPBYTE)&temp, 4);
// Notify the system about the changed settings
ev = CreateEvent(NULL, FALSE, FALSE, L"BackLightChangeEvent");
SetEvent(ev);
CloseHandle(ev);
 
// Allow the backlight thread to read the "0" timeout and turn off the dbacklight
Sleep(100);
// restore the original backlight timeout
RegSetValueEx(hKey, L"BatteryTimeout", 0, REG_DWORD, (LPBYTE)&batteryTimeout, 4);
RegSetValueEx(hKey, L"ACTimeout", 0, REG_DWORD, (LPBYTE)&acTimeout, 4);
CloseHandle(hKey);
 
// Force Backlight ON
// Set Event to turn on backlight
ev = CreateEvent(NULL, FALSE, FALSE, L"PowerManager/ActivityTimer/UserActivity");
SetEvent(ev);
CloseHandle(ev);
ev = CreateEvent(NULL, FALSE, FALSE, L"BackLightChangeEvent");
SetEvent(ev);
CloseHandle(ev);
 
return 0;

Display On/Off Events

The following pair of manual-reset events are signaled to indicate if the display is on or off:

• DisplayOnEvent
• DisplayOffEvent

The WaitForSingleObject() API function can be used to request the status or wait for these events.