Comment 3 for bug 1314678

This info was written by Seth Forshee (~sforshee) in February last year:

Android requires devices supply an xml config file that defines a number of brightness parameters. Among these is a table which defines ambient light sensor levels and the corresponding brightness which should be used at that ambient level. powerd supports reading in these files (currently they're located in
/usr/share/powerd/device_configs/config-<device>.xml). When autobrightness is enabled powerd requests ambient light level updates and maintains two moving averages of the ambient brightness, one "slow" and one "fast".

The slow average responds more slowly in changes to ambient brightness. It's used to decide when the ambient brightness has changed enough to trigger a reevaluation of screen brightness. This avoids too frequently changing the brightness for temporary ambient changes, e.g. quickly passing by a window.

Once the delta in slow average exceeds a hysteresis value, the fast average is used to determine the new brightness level. If the slow average were used the adjustment is too gradual, so using the fast average gets us to the new "ideal" brightness more quickly while still filtering out very brief transients and jitter in the sensor readings.

Once we've initiated a brightness change powerd will do a sort of polling every couple of seconds until the brightness level is at the ideal brightness for the ambient, within a hysteresis. In my testing it usually got within the hystersis on the first try, but occassionaly it required 2 or (rarely) 3.

Also a note about the ambient to screen brightness mappings. The table we get from android requires interpolation between the points. powerd uses monotonic cubic spline interpolation for this, because that's what Android uses for the same values (and it seems like an exceedingly reasonable choice besides).

So regarding your proposal. With what's there today we start with is a set of default manually defined brightness points which has been provided by the device manufacturer, which when combined with the
interpolation gives the mapping function you described. What would be missing is a algorithm to make adjustments to the table based on user feedback, APIs for making these adjustments, and a non-volatile location for storing the table after user changes have been made.

You seem to have an algorithm in mind, so I won't dwell on that, except to make one comment. What you seem to be trying to do is provide a way for the user to say, "map the ambient brightness level at this particular moment to the screen brightness I give you." The concern I would have about this would be races, i.e. the ambient brightness level changing such that the user-supplied brightness gets mapped to an ambient brightness other than the one which was intended. That said, I can't think of a better way to let the user tweak the autobrightness levels.

I think you should consider storage before the API, i.e. who will be storing the new user table. As of right now powerd doesn't store any user settings, and the widely agreed upon plan has been that as a system service it should not store user settings. If that model is maintained then the shell would need to store the table just like it's supposed to store the user-selected brightness or choice of ambient brightness setting. In that case you'd probably need a set of APIs similar to these to powerd:

* getAutobrightnessTable(): To allow the shell to read the autobrightness powerd is currently using (to get the default one before any user changes have been made).
* setAutobrightnessTable(): Tell powerd to start using the supplied mappings.
* getAmbientBrightness(): Read the current ambient brightness level. This could also be requested from the ALS directly, though the fast moving average may be a better value to target (except in conditions where ambient brightness actually is changing, but it seems like you're probably going to end up with poor results in that environment no matter what).

Of course if powerd were to do the storage then the set of APIs would be different.

Other APIs needed for brightness should already be present, see https://wiki.ubuntu.com/powerd.