From e6da737679a78c6e673a1629218fee4bcf488903 Mon Sep 17 00:00:00 2001 From: Beverly Date: Mon, 28 Feb 2022 20:09:39 +0000 Subject: [PATCH] Update doze docs * Rename aod.md => doze.md * Add burn-in section * Add doze suppressor section Test: manual Bug: 218509239 Change-Id: I4eb52989464f742b075d41f12f7fe4a759f94ebf --- packages/SystemUI/docs/keyguard.md | 2 +- .../docs/keyguard/{aod.md => doze.md} | 29 +++++++++++++++++-- 2 files changed, 27 insertions(+), 4 deletions(-) rename packages/SystemUI/docs/keyguard/{aod.md => doze.md} (57%) diff --git a/packages/SystemUI/docs/keyguard.md b/packages/SystemUI/docs/keyguard.md index 5e7bc1c8cad29..8914042ee3cdb 100644 --- a/packages/SystemUI/docs/keyguard.md +++ b/packages/SystemUI/docs/keyguard.md @@ -40,7 +40,7 @@ More coming [1]: /frameworks/base/packages/SystemUI/docs/keyguard/bouncer.md [2]: /frameworks/base/services/core/java/com/android/server/power/PowerManagerService.java -[3]: /frameworks/base/packages/SystemUI/docs/keyguard/aod.md +[3]: /frameworks/base/packages/SystemUI/docs/keyguard/doze.md [4]: /frameworks/base/services/core/java/com/android/server/policy/PhoneWindowManager.java diff --git a/packages/SystemUI/docs/keyguard/aod.md b/packages/SystemUI/docs/keyguard/doze.md similarity index 57% rename from packages/SystemUI/docs/keyguard/aod.md rename to packages/SystemUI/docs/keyguard/doze.md index 7f89984abdb32..a6ccab9698d44 100644 --- a/packages/SystemUI/docs/keyguard/aod.md +++ b/packages/SystemUI/docs/keyguard/doze.md @@ -1,9 +1,10 @@ -# Always-on Display (AOD) +# Doze -AOD provides an alternatative 'screen-off' experience. Instead, of completely turning the display off, it provides a distraction-free, glanceable experience for the phone in a low-powered mode. In this low-powered mode, the display will have a lower refresh rate and the UI should frequently shift its displayed contents in order to prevent burn-in. +Always-on Display (AOD) provides an alternative 'screen-off' experience. Instead, of completely turning the display off, it provides a distraction-free, glanceable experience for the phone in a low-powered mode. In this low-powered mode, the display will have a lower refresh rate and the UI should frequently shift its displayed contents in order to prevent burn-in. The recommended max on-pixel-ratio (OPR) is 5% to reduce battery consumption. -The default doze component is specified by `config_dozeComponent` in the [framework config][1]. SystemUI provides a default Doze Component: [DozeService][2]. [DozeService][2] builds a [DozeMachine][3] with dependencies specified in [DozeModule][4] and configurations in [AmbientDisplayConfiguration][13] and [DozeParameters][14]. +The default doze component controls AOD and is specified by `config_dozeComponent` in the [framework config][1]. SystemUI provides a default Doze Component: [DozeService][2]. [DozeService][2] builds a [DozeMachine][3] with dependencies specified in [DozeModule][4] and configurations in [AmbientDisplayConfiguration][13] and [DozeParameters][14]. +Note: The default UI used in AOD shares views with the Lock Screen and does not create its own new views. Once dozing begins, [DozeUI][17] informs SystemUI's [DozeServiceHost][18] that dozing has begun - which sends this signal to relevant SystemUI Lock Screen views to animate accordingly. Within SystemUI, [StatusBarStateController][19] #isDozing and #getDozeAmount can be used to query dozing state. [DozeMachine][3] handles the following main states: * AOD - persistently showing UI when the device is in a low-powered state * Pulsing - waking up the screen to show notifications (from AOD and screen off) @@ -42,6 +43,22 @@ Relevant sensors include: And are configured in the [AmbientDisplayConfiguration][13] with some related configurations specified in [DozeParameters][14]. +## Doze Suppressors +When Dozing is enabled, it can still be suppressed based on the device state. On a high-level, doze and/or AOD may be suppressed if the device is: +* in CAR_MODE +* not provisioned +* in power saver mode +* being suppressed by an app (see [PowerManager#suppressAmbientDisplay][16]) + +Refer to the documentation in [DozeSuppressors][15] for more information. + +## AOD burn-in and image retention +Because AOD will show an image on the screen for an elogated period of time, AOD designs must take into consideration burn-in (leaving a permanent mark on the screen). Temporary burn-in is called image-retention. + +To prevent burn-in, it is recommended to often shift UI on the screen. [DozeUi][17] schedules a call to dozeTimeTick every minute to request a shift in UI for all elements on AOD. The amount of shift can be determined by undergoing simulated AOD testing since this may vary depending on the display. + +For manual local testing, set [DozeUI][17]#BURN_IN_TESTING_ENABLED to true, and then manual time broadcasts (ie: `adb shell 'date 022202222022.00 ; am broadcast -a android.intent.action.TIME_SET'`) will update the burn-in translations of the views. For a general idea where burn-in may be an issue, run the [software burn-in script][20]. + ## Debugging Tips Enable DozeLog to print directly to logcat: ``` @@ -75,3 +92,9 @@ Other helpful dumpsys commands (`adb shell dumpsys `): [12]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeSensors.java [13]: /frameworks/base/core/java/android/hardware/display/AmbientDisplayConfiguration.java [14]: /frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/phone/DozeParameters.java +[15]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeSuppressor.java +[16]: /frameworks/base/core/java/android/os/PowerManager.java +[17]: /frameworks/base/packages/SystemUI/src/com/android/systemui/doze/DozeUi.java +[18]: /frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/phone/DozeServiceHost.java +[19]: /frameworks/base/packages/SystemUI/plugin/src/com/android/systemui/plugins/statusbar/StatusBarStateController.java +[20]: /frameworks/base/packages/SystemUI/docs/clock-plugins.md