Backlight fading

Welcome to the Backlight fading API page. This page aims to describe numerous approaches to achieve backlight fading.

Work in progress

The backlight thread

All backlight (and buttonlight) operation is done in the backlight thread apart from the rest of the code. The backlight thread accesses (initiates fading in and off) backlight fading by calling when the backlight times out:

void backlight_setup_fade_up(void)

and

void backlight_setup_fade_up(void)

Both set the prerequisites for the fading process. The fading process depends on the actual implementation.

The settings can access the fading and change its behaviour by calling

void backlight_set_fade_out(void)

and

void backlight_set_fade_in(void)

There is no replacement for the target specific

void _backlight_on(void)

and

void _backlight_off(void)

These want to be called no matter of the fading. This is also true for PWM fading, although the the target specific functions have different names for historical reasons (could be fixed).

After fading is done, the backlight thread initiates putting the LCD to sleep, and wakes it up before fading respectively:

void backlight_lcd_sleep_countdown(bool start)

PWM backlight fading

Backlight fading functions in that way:

• a) Setting up the ISR for the user timer hardware.
• b) Changing the PWM in that ISR in a fast fashion (several times per tick)

It delivers very smooth fading with virtually unlimited brightness levels.

Therefore, it requires a hardware-side mechanism which is able to change the PWM very quickly. Currently, it's implemented for a few iPods, the h100 series and the M:Robe 100.

For PWM (interrupt driven) backlight fading, there's currently one define:

• BACKLIGHT_FADING_PWM

The avaliable options are several overall times the backlight fading takes to toggle backlight completely.

Software driven backlight fading

Currently software driven backlight fading is solely implemented by changing the brightness in a given interval based on the total available brightness levels.

Backlight fading functions in that way:

• a) Changing the brightness upon enabling and disabling the backlight through the available (limited) brightness levels
• b) De/Incrementing the brightness level in a given interval fixed for a device in the backlight thread

It's completely software driven. It's limited in terms of smoothness (although the interval is optimized to be smooth) and configurability. It's relatively easy to adapt and doesn't require special hardware features. Additionally, it's dependent on the current backlight brightness value.

Therefore there's two defines:

• BACKLIGHT_FADING_SW_HW_REG and
• BACKLIGHT_FADING_SW_SETTING

There's 2 subimplementations, which are mainly caused by the subtle difference in hardware handling in brightness levels. There's a kind of controllers, that set the brightness to the lowest possible level upon backlight_off, while the other kind sets the backlight to off by setting the backlight brightness level to zero.

This type is currently used by most Sansas, the h300 series, M:Robe 500, Cowon D2, Philips players and the Ondas.

The available options are limited to ON and OFF. Using timer options are generally possible, but are likely to be problematic with high latency backlight changing hardware and/or being choppy while fading due to a rather high timer.

Handling backlight fading target specific

Backlight fading functions in that way:

• a) Enable whatever bits the hardware needs to handle fading itself.
• b) Rockbox mostly completely ignores it, as it can't really control it. It offers settings though, as far as possible.

It's completely hardware driven. Rockbox has no influence (at least currently for the targets that use it), other than toggling it on or off.

All fading is handled in the target specific _backlight_on()/_off() function. Fading must be finished until _backlight_off/_on() returns to prevent confusion of the backlight thread. The backlight thread handles this type as if there was no backlight fading

The configurability basically depends on the target, but currently only ON and OFF are used.

Currently, only the Gigabeat S and Gigabeat F implement it, although the latter doesn't #define BACKLIGHT_FADING_TARGET and thus doesn't feature configurability.

The corresponding define is

• BACKLIGHT_FADING_TARGET

(It's not strictly needed, as Rockbox doesn't acknowledge it. It only serves for adding the setting).