fuquan/allwinner_a64
1
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

upload android base code part8

Browse source
This commit is contained in:
August 2018-08-08 20:10:12 +08:00
parent 841ae54672
commit 5425409085
57075 changed files with 9846578 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

172
android/docs/source.android.com/en/devices/tech/display/app-shortcuts.html Normal file
View file

@ -0,0 +1,172 @@
<html devsite>
<head>
<title>App Shortcuts</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>
The Android 7.1.1 release allows developers to define action-specific
shortcuts in their apps that can be displayed in a launcher. These <a
href="https://developer.android.com/guide/topics/ui/shortcuts.html">app
shortcuts</a> let users quickly start common or recommended tasks within an
app.
</p>
<h2 id="overview">Overview</h2>
<p>
Each shortcut references an intent that launches a specific action in the app
when users select the shortcut. Examples of actions you can express as app
shortcuts include:
</p>
<ul>
<li>Navigating users to a particular location in a mapping app
<li>Sending messages to a friend in a communication app
<li>Playing the next episode of a TV show in a media app
<li>Loading the last save point in a gaming app</li></ul>
<h2 id="examples-and-source">Examples and source</h2>
<p>
You can find the primary implementation of this feature in the following files:
</p>
<pre class="devsite-click-to-copy">
frameworks/base/services/core/java/com/android/server/policy/ShortcutManager.java
frameworks/base/services/core/java/com/android/server/pm/ShortcutPackage.java
frameworks/base/services/core/java/com/android/server/pm/ShortcutUser.java
frameworks/base/services/core/java/com/android/server/pm/ShortcutPackageInfo.java
frameworks/base/services/core/java/com/android/server/pm/ShortcutLauncher.java
frameworks/base/services/core/java/com/android/server/pm/ShortcutParser.java
frameworks/base/services/core/java/com/android/server/pm/ShortcutService.java
frameworks/base/services/core/java/com/android/server/pm/LauncherAppsService.java
frameworks/base/services/core/java/com/android/server/pm/ShortcutPackageItem.java
frameworks/base/core/java/com/android/server/backup/ShortcutBackupHelper.java
frameworks/base/core/java/android/content/pm/ShortcutManager.java
frameworks/base/core/java/android/content/pm/ShortcutServiceInternal.java
frameworks/base/core/java/android/content/pm/ShortcutInfo.java
frameworks/base/core/java/android/content/pm/LauncherApps.java
</pre>
<p>
With the following files providing supporting features (called hidden APIs in
<code>ShortcutManager.java</code>):
</p>
<pre class="devsite-click-to-copy">
packages/apps/Settings/src/com/android/settings/DevelopmentSettings.java
frameworks/base/packages/SystemUI/src/com/android/systemui/statusbar/policy/RemoteInputView.java
</pre>
<p>
And, for an example, the Android Open Source Project Launcher version 3 supports
shortcuts:
</p>
<pre class="devsite-click-to-copy">
packages/apps/Launcher3/
</pre>
<p>
Finally, see the following files for public Javadoc.
</p>
<pre class="devsite-click-to-copy">
frameworks/base/core/java/android/content/pm/ShortcutManager.java
frameworks/base/core/java/android/content/pm/ShortcutInfo.java
frameworks/base/core/java/android/content/pm/LauncherApps.java
</pre>
<h2 id="implementation">Implementation</h2>
<p>
The AOSP Launcher3 supports shortcuts already. In cases where a partner has its
own launcher, that launcher should support shortcuts too.
</p>
<ul>
<li>When the user performs a certain gesture (e.g. long press) on an app icon,
the launcher should show the dynamic and manifest shortcuts associated with each
launcher activity icon.<br>
The shortcut sort order is defined in the ShorctutManager Javadoc within
the "Shortcut Display Order" section. For example, show the manifest shortcuts
first, then the dynamic shortcuts. The shortcuts are sorted by rank in
ascending order within each group.
<li>The user should be able to drag each dynamic/manifest shortcut and "pin" it
to the home screen.
<li>Pinned shortcuts should be backed up and restored. (See ShortcutManager's
javadoc for details)
<li>Doing an "Inline reply" on Notification should internally call
ShortcutManager.onApplicationActive.
</ul>
<p>
In addition, some Google Mobile Services (GMS) apps have shortcuts. The OEM
launcher should show shortcuts for them and ideally support "<a
href="https://support.google.com/nexus/answer/6118421">pinning</a>" (or creating
a shortcut icon) too.
</p>
<p>
See the Launcher3 source for details on how to interact with the framework for
the above operations.
</p>
<h2 id="validation">Validation</h2>
<p>
Use the following Android Compatibility Test Suite (CTS) tests to ensure your
version of the feature (ShortcutManager and LauncherApps) works as intended:
</p>
<pre class="devsite-click-to-copy">
cts/tests/tests/shortcutmanager/
cts/hostsidetests/shortcuts/
</pre>
<p>
And find the unit tests for the AOSP implementation here:
</p>
<pre class="devsite-click-to-copy">
frameworks/base/services/tests/servicestests/
</pre>
<p>
Which includes:
</p>
<pre class="devsite-click-to-copy">
src/com/android/server/pm/ShortcutManagerTest*.java
</pre>
<p>
You may also employ the CTS Verifier test for shortcut manager:
</p>
<pre class="devsite-click-to-copy">
cts/apps/CtsVerifier/src/com/android/cts/verifier/notifications/ShortcutThrottlingResetActivity.java
</pre>
</body>
</html>

47
android/docs/source.android.com/en/devices/tech/display/circular-icons.html Normal file
View file

@ -0,0 +1,47 @@
<html devsite>
<head>
<title>Implementing Circular Icons</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>Circular <a
href="https://developer.android.com/guide/practices/ui_guidelines/icon_design_launcher.html">launcher
icons</a> are supported in Android 7.1.1 and later. Circular launcher icons
are not enabled by default. To use circular icons in your device
implementation, you must edit the <a
href="/source/add-device.html#use-resource-overlays">resource
overlay</a> on your device to enable them.</p>
<p>The resource file you are using an overlay on is at:
<code><a
href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml">frameworks/base/core/res/res/values/config.xml</a></code>
<p>To enable circular icons, change the <code>config_useRoundIcon</code>
setting in your overlay file from <code>false</code> to <code>true</code>:</p>
<pre class="devsite-click-to-copy">
&lt;!-- Flag indicating whether round icons should be parsed from the application manifest. --&gt;
&lt;bool name="config_useRoundIcon"&gt;true&lt;/bool&gt;
</pre>
</body>
</html>

72
android/docs/source.android.com/en/devices/tech/display/dnd.html Normal file
View file

@ -0,0 +1,72 @@
<html devsite>
<head>
<title>Configuring DND</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>Android 7.0 supports the following do not disturb (DND) configurations.</p>
<h2 id="third_party">Third-party automatic rules</h3>
<p>Third-party applications can use the DND Access API to control DND rules:</p>
<ul>
<li><strong>Applications</strong> can export and list custom DND rules, which
appear next to built-in Android DND rules in the DND settings.</li>
<li><strong>Users</strong> can access all DND controls for all rules (both
automatic and manually-created).</li>
<li>The <strong>platform</strong> can implement DND rules from different sources
without creating unexpected states.</li>
</ul>
<h2 id="control_alarms">Controlling alarms</h3>
<p>When DND mode is enabled, the Android settings UI presents user options for
configuring:</p>
<ul>
<li><strong>DND end condition as next alarm time</strong>. Enables user to set
the DND end condition to an alarm. Appears only if an alarm is set for a time
within a week from now <em>and</em> the day of the week for that alarm is
<em>not</em> the same day of the week as today. (Not supported for automatic
rules.)</li>
<li><strong>Alarm can override end time</strong>. Enables users to configure the
DND end condition as a specific time or next alarm (whichever comes first).</li>
</ul>
<h2 id="suppress_vis_distract">Suppressing visual distractions</h3>
<p>The Android settings UI presents user options for suppressing visual
distractions such as heads up notifications, fullscreen intents, ambient
display, and LED notification lights.</p>
<h2 id="implementation">Customizing DND settings</h2>
<p>When customizing settings, OEMs must preserve the AOSP behavior of the system
APIs and maintain the behavior of DND settings. Specifically, the DND settings
page in system settings must include the following:</p>
<ul>
<li><strong>Application-provided DND rules</strong>. These automated DND rules
must include active rules instances and rule listings in the Add Rule menu.</li>
<li><strong>Pre-loaded application DND rules</strong>. OEMs can provide DND
rules that appear next to end user manually-created rules.</li>
</ul>
<p>For details on new DND APIs, refer to
<code><a href="https://developer.android.com/reference/android/service/notification/package-summary.html">android.service.notification</a></code>
reference documentation.</p>
</body>
</html>

707
android/docs/source.android.com/en/devices/tech/display/hdr.html Normal file
View file

@ -0,0 +1,707 @@
<html devsite>
<head>
<title>HDR Video Playback</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>High dynamic range (HDR) video is the next frontier in high-quality
video decoding, bringing unmatched scene reproduction qualities. It does
so by significantly increasing the dynamic range of the luminance component
(from the current 100 cd/m<sup>2</sup> to 1000s of cd/m<sup>2</sup>) and by using a much wider
color space (BT 2020). This is now a central element of the 4K UHD evolution
in the TV space.</p>
<p>In Android 7.0, initial HDR support has been added, which includes the
creation of proper constants for the discovery and setup of HDR video
pipelines. That means defining codec types and display modes and specifying
how HDR data must be passed to MediaCodec and supplied to HDR decoders. HDR
is only supported in tunneled video playback mode.</p>
<p>The purpose of this document is to help application developers support HDR stream
playback, and help OEMs and SOCs enable the HDR features on Android 7.0.</p>
<h2 id="technologies">Supported HDR technologies</h2>
<p>As of Android 7.0 release, the following HDR technologies are supported.
<table>
<tbody>
<tr>
<th>Technology
</th>
<th>Dolby-Vision
</th>
<th>HDR10
</th>
<th>VP9-HLG
</th>
<th>VP9-PQ
</th>
</tr>
<tr>
<th>Codec
</th>
<td>AVC/HEVC
</td>
<td>HEVC
</td>
<td>VP9
</td>
<td>VP9
</td>
</tr>
<tr>
<th>Transfer Function
</th>
<td>ST-2084
</td>
<td>ST-2084
</td>
<td>HLG
</td>
<td>ST-2084
</td>
</tr>
<tr>
<th>HDR Metadata Type
</th>
<td>Dynamic
</td>
<td>Static
</td>
<td>None
</td>
<td>Static
</td>
</tr>
</tbody>
</table>
<p>In Android 7.0, <b>only HDR playback via tunneled mode is defined</b>,
but devices may add support for playback of HDR on SurfaceViews using opaque
video buffers. In other words:</p>
<ul>
<li>There is no standard Android API to check if HDR playback is supported
using non-tunneled decoders.</li>
<li>Tunneled video decoders that advertise HDR playback capability must
support HDR playback when connected to HDR-capable displays.</li>
<li>GL composition of HDR content is not supported by the AOSP Android
7.0 release.</li>
</ul>
<h2 id="discovery">Discovery</h2>
<p>HDR Playback requires an HDR-capable decoder and a connection to an
HDR-capable display. Optionally, some technologies require a specific
extractor.</p>
<h3 id="display">Display</h3>
<p>Applications shall use the new <code>Display.getHdrCapabilities</code>
API to query the HDR technologies supported by the specified display. This is
basically the information in the EDID Static Metadata Data Block as defined
in CTA-861.3:</p>
<ul>
<li><code>public Display.HdrCapabilities getHdrCapabilities()</code><br>
Returns the display's HDR capabilities.</li>
<li><code>Display.HdrCapabilities</code><br>
Encapsulates the HDR capabilities of a given display. For example, what HDR
types it supports and details about the desired luminance data.</li>
</ul>
<p><b>Constants:</b></p>
<ul>
<li><code>int HDR_TYPE_DOLBY_VISION</code><br>
Dolby Vision support.</li>
<li><code>int HDR_TYPE_HDR10</code><br>
HDR10 / PQ support.</li>
<li><code>int HDR_TYPE_HLG</code><br>
Hybrid Log-Gamma support.</li>
<li><code>float INVALID_LUMINANCE</code><br>
Invalid luminance value.</li>
</ul>
<p><b>Public Methods:</b></p>
<ul>
<li><code>float getDesiredMaxAverageLuminance()</code><br>
Returns the desired content max frame-average luminance data in cd/cd/m<sup>2</sup> for
this display.</li>
<li><code>float getDesiredMaxLuminance()</code><br>
Returns the desired content max luminance data in cd/cd/m<sup>2</sup> for this display.</li>
<li><code>float getDesiredMinLuminance()</code><br>
Returns the desired content min luminance data in cd/cd/m<sup>2</sup> for this display.</li>
<li><code>int[] getSupportedHdrTypes()</code><br>
Gets the supported HDR types of this display (see constants). Returns empty
array if HDR is not supported by the display.</li>
</ul>
<h3 id="decoder">Decoder</h3>
<p>Applications shall use the existing
<a href="https://developer.android.com/reference/android/media/MediaCodecInfo.CodecCapabilities.html#profileLevels">
<code>CodecCapabilities.profileLevels</code></a> API to verify support for the
new HDR capable profiles:</p>
<h4>Dolby-Vision</h4>
<p><code>MediaFormat</code> mime constant:</p>
<pre class="devsite-click-to-copy">
String MIMETYPE_VIDEO_DOLBY_VISION
</pre>
<p><code>MediaCodecInfo.CodecProfileLevel</code> profile constants:</p>
<pre class="devsite-click-to-copy">
int DolbyVisionProfileDvavPen
int DolbyVisionProfileDvavPer
int DolbyVisionProfileDvheDen
int DolbyVisionProfileDvheDer
int DolbyVisionProfileDvheDtb
int DolbyVisionProfileDvheDth
int DolbyVisionProfileDvheDtr
int DolbyVisionProfileDvheStn
</pre>
<p>Dolby Vision video layers and metadata must be concatenated into a single
buffer per frames by video applications. This is done automatically by the
Dolby-Vision capable MediaExtractor.</p>
<h4>HEVC HDR 10</h4>
<p><code>MediaCodecInfo.CodecProfileLevel</code> profile constants:</p>
<pre class="devsite-click-to-copy">
int HEVCProfileMain10HDR10
</pre>
<h4>VP9 HLG & PQ</h4>
<p><code>MediaCodecInfo.CodecProfileLevel</code> profile
constants:</p>
<pre class="devsite-click-to-copy">
int VP9Profile2HDR
int VP9Profile3HDR
</pre>
<p>If a platform supports an HDR-capable decoder, it shall also support an
HDR-capable extractor.</p>
<p>Only tunneled decoders are guaranteed to play back HDR content. Playback
by non-tunneled decoders may result in the HDR information being lost and
the content being flattened into an SDR color volume.</p>
<h3 id="extractor">Extractor</h3>
<p>The following containers are supported for the various HDR technologies
on Android 7.0:</p>
<table>
<tbody>
<tr>
<th>Technology
</th>
<th>Dolby-Vision
</th>
<th>HDR10
</th>
<th>VP9-HLG
</th>
<th>VP9-PQ
</th>
</tr>
<tr>
<th>Container
</th>
<td>MP4
</td>
<td>MP4
</td>
<td>WebM
</td>
<td>WebM
</td>
</tr>
</tbody>
</table>
<p>Discovery of whether a track (of a file) requires HDR support is not
supported by the platform. Applications may parse the codec-specific data
to determine if a track requires a specific HDR profile.</p>
<h3 id ="summary">Summary</h3>
<p>Component requirements for each HDR technology are shown in the following table:</p>
<div style="overflow:auto">
<table>
<tbody>
<tr>
<th>Technology
</th>
<th>Dolby-Vision
</th>
<th>HDR10
</th>
<th>VP9-HLG
</th>
<th>VP9-PQ
</th>
</tr>
<tr>
<th>Supported HDR type (Display)
</th>
<td>HDR_TYPE_DOLBY_VISION
</td>
<td>HDR_TYPE_HDR10
</td>
<td>HDR_TYPE_HLG
</td>
<td>HDR_TYPE_HDR10
</td>
</tr>
<tr>
<th>Container (Extractor)
</th>
<td>MP4
</td>
<td>MP4
</td>
<td>WebM
</td>
<td>WebM
</td>
</tr>
<tr>
<th>Decoder
</th>
<td>MIMETYPE_VIDEO_DOLBY_VISION
</td>
<td>MIMETYPE_VIDEO_HEVC
</td>
<td>MIMETYPE_VIDEO_VP9
</td>
<td>MIMETYPE_VIDEO_VP9
</td>
</tr>
<tr>
<th>Profile (Decoder)
</th>
<td>One of the Dolby profiles
</td>
<td>HEVCProfileMain10HDR10
</td>
<td>VP9Profile2HDR or
VP9Profile3HDR
</td>
<td>VP9Profile2HDR or
VP9Profile3HDR
</td>
</tr>
</tbody>
</table>
</div>
<br>
<p>Notes:</p>
<ul>
<li>Dolby-Vision bitstreams are packaged in an MP4 container in a way defined
by Dolby. Applications may implement their own Dolby-capable extractors as
long as they package the access units from the corresponding layers into a
single access unit for the decoder as defined by Dolby.</li>
<li>A platform may support an HDR-capable extractor, but no corresponding
HDR-capable decoder.</li>
</ul>
<h2 id="playback">Playback</h2>
<p>After an application has verified support for HDR playback, it can play
back HDR content nearly the same way as it plays back non-HDR content,
with the following caveats:</p>
<ul>
<li>For Dolby-Vision, whether or not a specific media file/track requires
an HDR capable decoder is not immediately available. The application must
have this information in advance or be able to obtain this information by
parsing the codec-specific data section of the MediaFormat.</li>
<li><code>CodecCapabilities.isFormatSupported</code> does not consider whether
the tunneled decoder feature is required for supporting such a profile.</li>
</ul>
<h2 id="enablinghdr">Enabling HDR platform support</h2>
<p>SoC vendors and OEMs must do additional work to enable HDR platform
support for a device.</p>
<h3 id="platformchanges">Platform changes in Android 7.0 for HDR</h3>
<p>Here are some key changes in the platform (Application/Native layer)
that OEMs and SOCs need to be aware of.</p>
<h3 id="display">Display</h3>
<h4>Hardware composition</h4>
<p>HDR-capable platforms must support blending HDR content with non-HDR
content. The exact blending characteristics and operations are not defined
by Android as of release 7.0, but the process generally follows these steps:</p>
<ol>
<li>Determine a linear color space/volume that contains all layers to be
composited, based on the layers' color, mastering, and potential dynamic
metadata.
<br>If compositing directly to a display, this could be the linear space
that matches the display's color volume.</li>
<li>Convert all layers to the common color space.</li>
<li>Perform the blending.</li>
<li>If displaying through HDMI:
<ol style="list-style-type: lower-alpha">
<li>Determine the color, mastering, and potential dynamic metadata for the
blended scene.</li>
<li>Convert the resulting blended scene to the derived color
space/volume.</li>
</ol>
</li>
<li>If displaying directly to the display, convert the resulting blended
scene to the required display signals to produce that scene.
</li>
</ol>
<h4>Display discovery</h4>
<p>HDR display discovery is only supported via HWC2. Device implementers must
selectively enable the HWC2 adapter that is released with Android 7.0 for this
feature to work. Therefore, platforms must add support for HWC2 or extend the
AOSP framework to allow a way to provide this information. HWC2 exposes a new
API to propagate HDR Static Data to the framework and the application.</p>
<h4>HDMI</h4>
<ul>
<li>A connected HDMI display advertises
its HDR capability through HDMI EDID as defined in
<a href="https://standards.cta.tech/kwspub/published_docs/CTA-861.3-Preview.pdf">
CTA-861.3</a>
section 4.2.</li>
<li>The following EOTF mapping shall be used:
<ul>
<li>ET_0 Traditional gamma - SDR Luminance Range: not mapped to any HDR
type</li>
<li>ET_1 Traditional gamma - HDR Luminance Range: not mapped to any HDR
type</li>
<li>ET_2 SMPTE ST 2084 - mapped to HDR type HDR10</li>
</ul>
</li>
<li>The signaling of Dolby Vision or HLG support over HDMI is done as defined
by their relevant bodies.</li>
<li>Note that the HWC2 API uses float desired luminance values, so the 8-bit
EDID values must be translated in a suitable fashion.</li>
</ul>
<h3 id="decoders">Decoders</h3>
<p>Platforms must add HDR-capable tunneled decoders and advertise their HDR
support. Generally, HDR-capable decoders must:</p>
<ul>
<li>Support tunneled decoding (<code>FEATURE_TunneledPlayback</code>).</li>
<li>Support HDR static metadata
(<code>OMX.google.android.index.describeHDRColorInfo</code>) and its
propagation to the display/hardware composition. For HLG, appropriate metadata
must be submitted to the display.</li>
<li>Support color description
(<code>OMX.google.android.index.describeColorAspects</code>) and its
propagation to the display/hardware composition.</li>
<li>Support HDR embedded metadata as defined by the relevant standard.</li>
</ul>
<h4>Dolby Vision decoder support</h4>
<p>To support Dolby Vision, platforms must add a Dolby-Vision capable
HDR OMX decoder. Given the specifics of Dolby Vision, this is normally a
wrapper decoder around one or more AVC and/or HEVC decoders as well as a
compositor. Such decoders must:</p>
<ul>
<li>Support mime type "video/dolby-vision."</li>
<li>Advertise supported Dolby Vision profiles/levels.</li>
<li>Accept access units that contain the sub-access-units of all layers as
defined by Dolby.</li>
<li>Accept codec-specific data defined by Dolby. For example, data containing
Dolby Vision profile/level and possibly the codec-specific data for the
internal decoders.</li>
<li>Support adaptive switching between Dolby Vision profiles/levels as
required by Dolby.</li>
</ul>
<p>When configuring the decoder, the actual Dolby profile is not communicated
to the codec. This is only done via codec-specific data after the decoder
has been started. A platform could choose to support multiple Dolby Vision
decoders: one for AVC profiles, and another for HEVC profiles to be able to
initialize underlying codecs during configure time. If a single Dolby Vision
decoder supports both types of profiles, it must also support switching
between those dynamically in an adaptive fashion.</p>
<p>If a platform provides a Dolby-Vision capable decoder in addition to the
general HDR decoder support, it must:</p>
<ul>
<li>Provide a Dolby-Vision aware extractor, even if it does not support
HDR playback.</li>
<li>Provide a decoder that supports at least Dolby Vision profile X/level
Y.</li>
</ul>
<h4>HDR10 decoder support</h4>
<p>To support HDR10, platforms must add an HDR10-capable OMX decoder. This
is normally a tunneled HEVC decoder that also supports parsing and handling
HDMI related metadata. Such a decoder (in addition to the general HDR decoder
support) must:</p>
<ul>
<li>Support mime type "video/hevc."</li>
<li>Advertise supported HEVCMain10HDR10. HEVCMain10HRD10 profile support
also requires supporting the HEVCMain10 profile, which requires supporting
the HEVCMain profile at the same levels.</li>
<li>Support parsing the mastering metadata SEI blocks, as well as other HDR
related info contained in SPS.</li>
</ul>
<h4>VP9 decoder support</h4>
<p>To support VP9 HDR, platforms must add a VP9 Profile2-capable HDR OMX
decoder. This is normally a tunneled VP9 decoder that also supports handling
HDMI related metadata. Such decoders (in addition to the general HDR decoder
support) must:</p>
<ul>
<li>Support mime type "video/x-vnd.on2.vp9."</li>
<li>Advertise supported VP9Profile2HDR. VP9Profile2HDR profile support also
requires supporting VP9Profile2 profile at the same level.</li>
</ul>
<h3 id="extractors">Extractors</h3>
<h4>Dolby Vision extractor support</h4>
<p>Platforms that support Dolby Vision decoders must add Dolby extractor
(called Dolby Extractor) support for Dolby Video content.</p>
<ul>
<li>A regular MP4 extractor can only extract the base layer from a file,
but not the enhancement or metadata layers. So a special Dolby extractor is
needed to extract the data from the file.</li>
<li>The Dolby extractor must expose 1 to 2 tracks for each Dolby video track
(group):
<ul>
<li>A Dolby Vision HDR track with the type of "video/dolby-vision" for the
combined 2/3-layers Dolby stream. The HDR track's access-unit format, which
defines how to package the access units from the base/enhancement/metadata
layers into a single buffer to be decoded into a single HDR frame, is to be
defined by Dolby.</li>
<li>If a Dolby Vision video track contains a separate (backward compatible)
base-layer (BL), the extractor must also expose this as a separate "video/avc"
or "video/hevc" track. The extractor must provide regular AVC/HEVC access
units for this track.</li>
<li>The BL track must have the same track-unique-ID ("track-ID") as the
HDR track so the app understands that these are two encodings of the same
video.</li>
<li>The application can decide which track to choose based on the platform's
capability.</li>
</ul>
</li>
<li>The Dolby Vision profile/level must be exposed in the track format of
the HDR track.</li>
<li>If a platform provides a Dolby-Vision capable decoder, it must also provide
a Dolby-Vision aware extractor, even if it does not support HDR playback.</li>
</ul>
<h4>HDR10 and VP9 HDR extractor support</h4>
<p>There are no additional extractor requirements to support HDR10 or VP9
HLG. Platforms must extend MP4 extractor to support VP9 PQ in MP4. HDR
static metadata must be propagated in the VP9 PQ bitstream, such that this
metadata is passed to the VP9 PQ decoder and to the display via the normal
MediaExtractor =&gt; MediaCodec pipeline.</p>
<h3 id="stagefright">Stagefright extensions for Dolby Vision support</h3>
<p>Platforms must add Dolby Vision format support to Stagefright:</p>
<ul>
<li>Support for port definition query for compressed port.</li>
<li>Support profile/level enumeration for DV decoder.</li>
<li>Support exposing DV profile/level for DV HDR tracks.</li>
</ul>
<h2 id="implementationnotes">Technology-specific implementation details</h2>
<h3 id="hdr10decoder">HDR10 decoder pipeline</h3>
<p><img src="/devices/tech/images/hdr10_decoder_pipeline.png"></p>
<p class="img-caption"><strong>Figure 1.</strong> HDR10 pipeline</p>
<p>HDR10 bitstreams are packaged in MP4 containers. Applications use a regular
MP4 extractor to extract the frame data and send it to the decoder.</p>
<ul>
<li><b>MPEG4 Extractor</b><br>
HDR10 bitstreams are recognized as just a normal HEVC stream by a
MPEG4Extractor and the HDR track with the type "video/HEVC" will be
extracted. The framework picks an HEVC video decoder that supports the
Main10HDR10 profile to decode that track.</li>
<li><b>HEVC Decoder</b><br>
HDR information is in either SEI or SPS. The HEVC decoder first receives
frames that contain the HDR information. The decoder then extracts the HDR
information and notifies the application that it is decoding an HDR video. HDR
information is bundled into decoder output format, which is propagated to
the surface later.</li>
</ul>
<h4>Vendor actions</h4>
<ol>
<li>Advertise supported HDR decoder profile and level OMX type. Example:<br>
<code>OMX_VIDEO_HEVCProfileMain10HDR10</code> (and <code>Main10</code>)</li>
<li>Implement support for index:
'<code>OMX.google.android.index.describeHDRColorInfo</code>'</li>
<li>Implement support for index:
'<code>OMX.google.android.index.describeColorAspects</code>'</li>
<li>Implement support for SEI parsing of mastering metadata.</li>
</ol>
<h3 id="dvdecoder">Dolby Vision decoder pipeline</h3>
<p><img src="/devices/tech/images/dolby_vision_decoder_pipleline.png"></p>
<p class="img-caption"><strong>Figure 2.</strong> Dolby Vision pipeline</p>
<p>Dolby-bitstreams are packaged in MP4 containers as defined by
Dolby. Applications could, in theory, use a regular MP4 extractor to extract
the base layer, enhancement layer, and metadata layer independently; however,
this does not fit the current Android MediaExtractor/MediaCodec model.</p>
<ul>
<li>DolbyExtractor:
<ul>
<li>Dolby-bitstreams are recognized by a DolbyExtractor, which exposes the
various layers as 1 to 2 tracks for each dolby video track (group):
<ul>
<li>An HDR track with the type of "video/dolby-vision" for the combined
2/3-layers dolby stream. The HDR track's access-unit format, which defines
how to package the access units from the base/enhancement/metadata layers
into a single buffer to be decoded into a single HDR frame, is to be defined
by Dolby.</li>
<li>(Optional, only if the BL is backward compatible) A BL track contains
only the base layer, which must be decodable by regular MediaCodec decoder,
for example, AVC/HEVC decoder. The extractor should provide regular AVC/HEVC
access units for this track. This BL track must have the same track-unique-ID
("track-ID") as the Dolby track so the application understands that these
are two encodings of the same video.</li>
</ul>
<li>The application can decide which track to choose based on the platform's
capability.</li>
<li>Because an HDR track has a specific HDR type, the framework will pick
a Dolby video decoder to decode that track. The BL track will be decoded by
a regular AVC/HEVC video decoder.</li>
</ul>
<li>DolbyDecoder:
<ul>
<li>The DolbyDecoder receives access units that contain the required access
units for all layers (EL+BL+MD or BL+MD)</li>
<li>CSD (codec specific data, such as SPS+PPS+VPS) information for the
individual layers can be packaged into 1 CSD frame to be defined by
Dolby. Having a single CSD frame is required.</li>
</ul>
</ul>
<h4>Dolby actions</h4>
<ol>
<li>Define the packaging of access units for the various Dolby container
schemes (e.g. BL+EL+MD) for the abstract Dolby decoder (i.e. the buffer
format expected by the HDR decoder).</li>
<li>Define the packaging of CSD for the abstract Dolby decoder.</li>
</ol>
<h4>Vendor actions</h4>
<ol>
<li>Implement Dolby extractor. This can also be done by Dolby.</li>
<li>Integrate DolbyExtractor into the framework. The entry point is
<code>frameworks/av/media/libstagefright/MediaExtractor.cpp</code>.</li>
<li>Declare HDR decoder profile and level OMX
type. Example: <code>OMX_VIDEO_DOLBYPROFILETYPE</code> and
<code>OMX_VIDEO_DOLBYLEVELTYP</code>.</li>
<li>Implement support for index:
<code>'OMX.google.android.index.describeColorAspects</code>'</li>
<li>Propagate the dynamic HDR metadata to the app and surface in each
frame. Typically this information must be packaged into the decoded frame
as defined by Dolby, because the HDMI standard does not provide a way to
pass this to the display.</li>
</ol>
<h3 id="v9decoder">VP9 decoder pipeline</h3>
<p><img src="/devices/tech/images/vp9-pq_decoder_pipleline.png"></p>
<p class="img-caption"><strong>Figure 3.</strong> VP9-PQ pipeline</p>
<p>VP9 bitstreams are packaged in WebM containers in a way defined by WebM
team. Applications need to use a WebM extractor to extract HDR metadata from
the bitstream before sending frames to the decoder.</p>
<ul>
<li>WebM Extractor:
<ul>
<li>WebM Extractor extracts the HDR <a
href="http://www.webmproject.org/docs/container/#colour">metadata</a>
and frames from the <a
href="http://www.webmproject.org/docs/container/#location-of-the-colour-element-in-an-mkv-file">
container</a>.</li>
</ul>
<li>VP9 Decoder:
<ul>
<li>Decoder receives Profile2 bitstreams and decodes them as normal VP9
streams.</li>
<li>Decoder receives any HDR static metadata from the framework.</li>
<li>Decoder receives static metadata via the bitstream access units for VP9
PQ streams.</li>
<li>VP9 decoder must be able to propagate the HDR static/dynamic metadata
to the display.</li>
</ul>
</ul>
<h4>Vendor Actions</h4>
<ol>
<li>Implement support for index:
<code>OMX.google.android.index.describeHDRColorInfo</code></li>
<li>Implement support for index:
<code>OMX.google.android.index.describeColorAspects</code></li>
<li>Propagate HDR static metadata</li>
</ol>
</body>
</html>

BIN
android/docs/source.android.com/en/devices/tech/display/images/retail-demo-flow.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 14 KiB

BIN
android/docs/source.android.com/en/devices/tech/display/images/retail-demo-wizard.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 45 KiB

47
android/docs/source.android.com/en/devices/tech/display/index.html Normal file
View file

@ -0,0 +1,47 @@
<html devsite>
<head>
<title>Configuring Display Settings</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>This section covers AOSP implementation of various Android display
settings, including app shortcuts, circular launcher icons, do not disturb
(DND), multi-window (split-screen, free-form, and picture-in-picture), high
dynamic range (HDR) video, night light, and retail demo mode. See the subpages
of this section for details.</p>
<h2 id="settingshome">Settings Home screen enhancements</h2>
<p>In Android 7.0 and later, the Settings Home page is enhanced with suggested
settings and customizable status notifications. The feature is implemented
automatically, and device implementers can configure it.</p>
<p>The source code for these enhancements is in these files:</p>
<ul>
<li><code>frameworks/base/packages/SettingsLib/src/com/android/settingslib/SuggestionParser.java</code></li>
<li><code>frameworks/base/packages/SettingsLib/src/com/android/settingslib/drawer/TileUtils.java</code></li>
</ul>
</body>
</html>

125
android/docs/source.android.com/en/devices/tech/display/multi-window.html Normal file
View file

@ -0,0 +1,125 @@
<html devsite>
<head>
<title>Supporting Multi-Window</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>
In Android 7.0 and later, users can have multiple apps simultaneously displayed on their
device screen with the new platform feature, multi-window. In addition to the
default implementation of multi-window, Android also supports a few varieties
of multi-window:</p>
<ul>
<li><strong>Split-screen</strong> is the base implementation of multi-window and
provides two activity panes for users to place apps.
<li><strong>Freeform</strong> allows users to dynamically resize the activity
panes and have more than two apps visible on their screen.
<li><strong>Picture-in-picture (PIP)</strong> allows Android devices to continue
playing video content in a small window while the user interacts with other
applications.</li>
</ul>
<p>
To implement the multi-window feature, device manufacturers set a flag in the
config file on their devices to enable or disable multi-window support.
</p>
<h2 id="implementation">Implementation</h2>
<p>
Multi-window support is enabled by default in Android 7.0 and later. To disable it, set
the <code>config_supportsMultiWindow</code> flag to false in the <a
href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml">config.xml</a>
file.
</p>
<p>
For devices that declare <code>ActivityManager.isLowRam()</code>, multi-window
is disabled regardless of the value of <code>config_supportsMultiWindow</code>
flag.
</p>
<h3 id="split-screen">Split-screen</h3>
<p>
The default multi-window experience is split-screen mode, where the System UI is
divided directly down the middle of the device in portrait or landscape. Users
can resize the window by dragging the dividing line side-to-side or
top-to-bottom, depending on the device orientation.
</p>
<p>
Then device manufacturers can choose if they want to enable freeform or PIP.
</p>
<h3 id="freeform">Freeform</h3>
<p>
After enabling standard multi-window mode with the flag
<code>config_supportsMultiWindow</code>, device manufacturers can optionally
allow freeform windowing. This mode is most useful for manufacturers of larger
devices, like tablets.
</p>
<p>
To support freeform mode, enable the
PackageManager#FEATURE_FREEFORM_WINDOW_MANAGEMENT system feature in <a
href="https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/content/pm/PackageManager.java">/android/frameworks/base/core/java/android/content/pm/PackageManager.java</a>
and set <code>config_freeformWindowManagement</code> to true in <a
href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml">config.xml</a>.
</p>
<pre class="devsite-click-to-copy">
&lt;bool name="config_freeformWindowManagement"&gt;true&lt;/bool&gt;
</pre>
<h3 id="picture-in-picture">Picture-in-picture</h3>
<p>
After enabling standard multi-window mode with the flag
<code>config_supportsMultiWindow</code>, device manufacturers can support <a
href="https://developer.android.com/training/tv/playback/picture-in-picture.html">picture-in-picture</a>
to allow users to continue watching video while browsing other activities.
While this features is primarily targeted at Android Television devices, other
device form factors may support this feature.
</p>
<p>
To support PIP, enable the PackageManager#FEATURE_PICTURE_IN_PICTURE system
feature in <a
href="https://android.googlesource.com/platform/frameworks/base/+/master/core/java/android/content/pm/PackageManager.java">/android/frameworks/base/core/java/android/content/pm/PackageManager.java</a>.
</p>
<h3 id="system-ui">System UI</h3>
<p>
Support all standard System UIs according to <a
href="https://developer.android.com/guide/topics/ui/multi-window.html#testing">
https://developer.android.com/guide/topics/ui/multi-window.html#testing</a>
</p>
<h3 id="applications">Applications</h3>
<p>
To support multi-window mode for preloaded apps, consult the <a
href="https://developer.android.com/guide/topics/ui/multi-window.html">Android
developer documentation</a>.
</p>
<h2 id="validation">Validation</h2>
<p>
To validate their implementation of multi-window, device manufacturers should
run <a
href="https://android.googlesource.com/platform/cts/+/master/hostsidetests/services/activitymanager/src/android/server/cts">CTS
tests</a> and follow the <a
href="https://developer.android.com/guide/topics/ui/multi-window.html#testing">testing
instructions for multi-window</a>.
</p>
</body>
</html>

147
android/docs/source.android.com/en/devices/tech/display/night-light.html Normal file
View file

@ -0,0 +1,147 @@
<html devsite>
<head>
<title>Implementing Night Light</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>
Research suggests that blue light from screens can have a negative impact on
sleep. Android 7.1.1 includes a feature called Night Light that reduces the
amount of blue light emitted by the device display to better match the natural
light of the user's time of day and location.
</p>
<p>
Night Light requires a
<a href="/devices/graphics/implement-hwc.html">Hardware
Composer HAL 2.0</a> (HWC 2) implementation that can apply the matrix passed to
<code>setColorTransform</code> to perform tinting without impacting power,
performance, and app compatibility.
</p>
<h2 id="implementation">Implementation</h2>
<p>
Device manufacturers can enable the default implementation of the feature by
using the following flags defined in:
<code><a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/values/config.xml">
/android/frameworks/base/core/res/res/values/config.xml</a></code>
<pre class="devsite-click-to-copy">
&lt;!-- Control whether Night display is available. This should only be enabled
on devices with HWC 2 color transform support. --&gt;
&lt;bool name="config_nightDisplayAvailable">false&lt;/bool&gt;
&lt;!-- Default mode to control how Night display is automatically activated.
One of the following values (see NightDisplayController.java):
0 - AUTO_MODE_DISABLED
1 - AUTO_MODE_CUSTOM
2 - AUTO_MODE_TWILIGHT
--&gt;
&lt;integer name="config_defaultNightDisplayAutoMode">0&lt;/integer&gt;
&lt;!-- Default time when Night display is automatically activated.
Represented as milliseconds from midnight (e.g. 79200000 == 10pm). --&gt;
&lt;integer name="config_defaultNightDisplayCustomStartTime">79200000&lt;/integer&gt;
&lt;!-- Default time when Night display is automatically deactivated.
Represented as milliseconds from midnight (e.g. 21600000 == 6am). --&gt;
&lt;integer name="config_defaultNightDisplayCustomEndTime">21600000&lt;/integer&gt;
</pre>
<p>
The code is divided between framework, system services, SystemUI, and Settings:
</p>
<pre class="devsite-click-to-copy">
platform/frameworks/base/core
├ java/android/provider/Settings.java
├ java/com/android/internal/app/NightDisplayController.java
└ res/res/values/config.xml
platform/frameworks/base/proto/src/metrics_constants.proto
platform/frameworks/base/services
├ core/java/com/android/server/display/DisplayManagerService.java
├ core/java/com/android/server/display/DisplayTransformManager.java
├ core/java/com/android/server/display/NightDisplayService.java
└ java/com/android/server/SystemServer.java
platform/frameworks/base/packages/SystemUI
├ res/drawable/ic_qs_night_display_off.xml
├ res/drawable/ic_qs_night_display_on.xml
├ res/values/strings.xml
└ src/com/android/systemui/qs/tiles/NightDisplayTile.java
platform/packages/apps/Settings
├ AndroidManifest.xml
├ res/drawable/ic_settings_night_display.xml
├ res/values/strings.xml
├ res/xml/display_settings.xml
├ res/xml/night_display_settings.xml
├ src/com/android/settings/Settings.java
├ src/com/android/settings/dashboard/conditional/NightDisplayCondition.java
├ src/com/android/settings/display/NightDisplayPreference.java
└ src/com/android/settings/display/NightDisplaySettings.java
</pre>
<h2 id="ui-features">UI features</h2>
<p>
Because Night Light is a user-facing feature, users need to be able to control
it. There is a full implementation of the settings in the Android Open Source
Project (AOSP)
<a href="https://android.googlesource.com/platform/packages/apps/Settings/">packages/apps/Settings</a>
project that device manufacturers can reference for their Settings
implementation.
</p>
<h3 id="settings">Settings</h3>
<p>
The settings for Night Light are in <em>Settings &gt; Display &gt; Night
Light</em>. From there, users can learn about Night Light, set its schedule,
and turn it on or off.
</p>
<ul>
<li><strong>Turn On Automatically</strong>
<ul>
<li><strong>Never</strong>: Night Light will never turn on automatically and
must be activated with the manual <strong>On / Off</strong> toggle.</li>
<li><strong>Custom schedule</strong>: Night Light turns on at a specified
<strong>Start time </strong>[default: 10:30 p.m.] and off at a specified
<strong>End time</strong> [default: 6:30 a.m.].</li>
<li><strong>Sunset to sunrise</strong>: Night Light turns on at sunset and off
at sunrise. The time for sunrise and sunset depends on the device location
and the time of year.</li>
</ul>
</li>
<li><strong>On / Off</strong>: Toggle that controls the current state of Night
Light. This state respects existing automatic rules. For example, if Night
Light is toggled on at 5:30 p.m. (before the automatic rule would turn it on
at 10:30 p.m.), Night Light will still turn off at 6:30 a.m. And if Night
Light is toggled off at 5:30 a.m. (before it turns off at 6:30 a.m.), it will
still turn on at 10:30 p.m.</li>
<li><strong>Informational text</strong>: Teaches the user what Night Light does
and why.</li>
</ul>
<h3 id="settings-conditional">Settings conditional</h3>
<p>
Visible at the top of Settings when Night Light is on.
</p>
<h3 id="quick-settings-tile">Quick Settings tile</h3>
<p>
The Quick Settings tile behaves identically to the <strong>On / Off</strong>
toggle in <em>Settings &gt; Display &gt; Night Light</em>.
</p>
</body>
</html>

336
android/docs/source.android.com/en/devices/tech/display/retail-mode.html Normal file
View file

@ -0,0 +1,336 @@
<html devsite>
<head>
<title>Retail Demo Mode</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>
Android 7.1.1 and later offer system-level support for retail mode so
users may readily examine the devices in action. This feature enables anyone in
a retail environment to get a quick, safe, and consistent demonstration of an
Android device and significantly reduce the cost and complexity of a retail mode
for OEMs so that demonstration units are commonplace.
</p>
<h2 id="key-use-cases">Key use cases</h2>
<ul>
<li>Any off-the-shelf Android device can be set to retail mode by adding a
single demo video to the build.
<li>All devices have a video highlighting the unique features of the device.
<li>Devices work in both online and offline environments.
<li>Device are self maintaining, requiring minimal interaction by
employees.</li></ul>
<h2 id="lifecycle">Lifecycle</h2>
<img src="/devices/tech/display/images/retail-demo-flow.png" alt="retail demo mode flow" width="XXX" id="retail-demo-flow" />
<p class="img-caption">
<strong>Figure 1.</strong> Retail demonstration mode option in Language selection
</p>
<h3 id="setup-wizard-suw">Setup Wizard (SUW)</h3>
<p>
Retail employees can enable retail mode directly from the first screen of any setup
wizard by selecting the language <strong>Retail demo</strong> at the bottom of
the list. This option is available for new devices shipped fresh from the
factory. Once a consumer setup has completed, retail mode may no longer be
available. Once selected, the device finishes SUW with an abbreviated flow.
</p>
<img src="/devices/tech/display/images/retail-demo-wizard.png" alt="retail demo wizard use" width="XXX" id="retail-demo-wizard" />
<p class="img-caption">
<strong>Figure 2.</strong> Retail demonstration mode option in Language
selection
</p>
<h3 id="guest-session">Guest session</h3>
<p>
When the device enters retail mode, it switches to a new demo user and
automatically starts the custom launcher specified in the overlay resource
(described under Implementation). By default, this custom launcher plays the
demo video on repeat until the user touches the screen to begin a guest session.
At that time, the custom launcher starts the system launcher and then exits.
OEMs can alter the custom launcher to additionally launch another service or
activity on exit. See the <em>Implementation</em> section for details.
</p>
<p>
In order to maintain the integrity of retail mode, keyguard is disabled and
certain actions from Quick Settings that could adversely affect retail mode are
also disallowed, including:
</p>
<ul>
<li>Airplane mode toggle
<li>Removing or modifying Wi-Fi access points (Settings)
<li>Changing carrier (Settings)
<li>Configuring hotspot (Settings)
<li>User switching
</ul>
<p>
Additionally, access is also blocked to some global settings that can affect
retail mode by disabling:
</p>
<ul>
<li>Wi-Fi settings
<li>Cellular network configuration options, particularly hotspots
<li>Bluetooth configuration
<li>Backup & Reset, Date & Time, and Mobile Networks (they do not show up at
all)
</ul>
<p>
If the user is idle for some period of time (90 seconds by default), retail mode
will show a system dialog to prompt the user to either exit the session or
continue. If the user chooses to exit or if there's no response for five
seconds, retail mode kills/wipes the current demo user, switches to a new demo
user, and loops through the original video again. If someone turns off the
screen using the power button, it comes back on automatically after a few
seconds.
</p>
<p>
After exiting a demo session, devices mute themselves and reset some global
settings, including:
</p>
<ul>
<li>Brightness
<li>Auto-rotation
<li>Flashlight
<li>Language
<li>Accessibility</li></ul>
<h3 id="exiting-retail-mode">Exiting retail mode</h3>
<p>
In order to exit retail mode, retail employees must factory reset the device
from the boot loader.
</p>
<h2 id="examples-and-source">Examples and source</h2>
<p>
Find the custom launcher that plays a video in a loop within:</p>
<pre class="devsite-click-to-copy">
/packages/apps/RetailDemo
</pre>
<h2 id="implementation">Implementation</h2>
<h3 id="enabling-retaildemomodeservice">Enabling RetailDemoModeService</h3>
<p>
Setup wizard sets a Global setting <code>Global.DEVICE_DEMO_MODE=true</code> to
indicate that the device has entered retail mode. Upon seeing this setting,
<code>RetailDemoModeService</code> creates and switches to demo user when user 0
is started, enables the custom launcher specified in an overlay resource, and
disables SUW. System Server and SystemUI also use this flag to manage aspects
of retail mode.
</p>
<h3 id="setting-custom-launcher-or-video-player">Setting custom launcher or
video player</h3>
<p>
An OEM specifies a custom launcher by overriding the framework resource
<code>config_demoModeLauncherComponent</code> specified in:
<code>/frameworks/base/core/res/res/config.xml</code>
</p>
<p>
For example, with:
</p>
<pre class="devsite-click-to-copy">
&lt;!-- Component that is the default launcher when Retail Mode is enabled. --&gt;
&lt;string name="config_demoModeLauncherComponent"&gt;com.android.retaildemo/.DemoPlayer&lt;/string&gt;
</pre>
<p>
The retail demo DemoPlayer app located at
<code>/packages/apps/RetailDemo</code> is the default custom launcher in the
Android Open Source Project (AOSP). The app looks for a video in
<code>/data/preloads/demo/retail_demo.mp4</code> and plays it in a loop. When
the user touches the screen, the custom launcher disables its activity
component, which results in the default system launcher starting up.
</p>
<p>The custom launcher must have its custom component marked as disabled by default so that it
doesn't show up in non-demo scenarios. In the demo scenario, System Server
enables the specified <code>config_demoModeLauncherComponent</code> when
starting a new demo session.
</p>
<p>
Setup wizard also looks for the above video to provide an affordance to enter
retail mode. SUW can be modified to look for some other OEM-specific sign that
retail mode is supported if the video is not a part of the demo.
</p>
<p>
If there are system A/B partitions, the system B partition must contain the demo
video at <code>/preloads/demo</code>. This gets copied to
<code>/data/preloads/demo</code> on first boot.
</p>
<p>
To set retail mode-specific settings, use:
<code>Settings.Global.retail_demo_mode_constants</code>. E.g.:
<code>user_inactivity_timeout_ms=90000,warning_dialog_timeout_ms=10000</code>
</p>
<p class="note"><strong>Note:</strong> 90000 milliseconds is the current
timeout default but is configurable.
</p>
<h3 id="finding-sample-images">Finding sample images</h3>
<p>
This feature places sample photos in a special folder that is visible to any
gallery app. The photos are available only in demo mode and cannot be modified
by the demo user as they are in a protected directory.
</p>
<h3 id="preventing-google-accounts">Preventing Google accounts</h3>
<p>
Certain restrictions are set in the guest user, similar to managed
device/profile policies that prevent apps and users from performing certain
operations. One of these restrictions is <code>DISALLOW_MODIFY_ACCOUNTS</code>.
With this restriction, AccountManager and Settings do not allow the addition of
accounts. Some Google apps react to this restriction and show an error message,
and others will not prompt for an account (such as YouTube and Photos).
</p>
<p>
OEM apps should also check if <code>DISALLOW_MODIFY_ACCOUNTS</code> is set. But this is a
general problem not unique to retail mode. It is likely already solved for
enterprise use cases.
</p>
<h3 id="customizing-the-system-launcher">Customizing the system launcher</h3>
<p>
OEMs are free to choose their layout but should include apps that function well
on the home screen and hotseat.
</p>
<h3 id="Customizing-built-in-apps">Customizing built-in apps for retail demo mode</h3>
<p>
Built-in apps may have their experience for retail demo mode customized by
calling the API <code>UserManager.isDemoUser()</code> to see if the app is
launched in a demo environment.
</p>
<h3 id="following-demo-video-guidelines">Following demo video guidelines</h3>
<p>
Demonstration videos should be in portrait layout (or natural orientation of the
device, if tablet) and can be any length greater than five seconds. Content
should not result in burn-in, since it will be played 24/7 when on display.
</p>
<h2 id="maintenance">Maintenance</h2>
<h3 id="bringing-the-device-out-of-retail-mode">Bringing the device out of
retail mode</h3>
<p>
This can be done only by factory resetting from the boot loader.
</p>
<h3 id="auto-ota-of-system-software">Auto-OTA of system software</h3>
<p>
By default, when retail mode is enabled, device policy is set to over-the-air
(OTA) update automatically. Retail devices will download, reboot, and install
the update (respecting battery thresholds) without confirmation even if it is
marked as optional.
</p>
<p class="caution"><strong>Caution:</strong>
If using System A/B partitions for OTA, once an OTA is received, the device
cannot find original retail mode resources in the System B partition. So any
subsequent factory reset will result in an inability to go back into retail
mode.
</p>
<h3 id="updating-demo-video-via-the-web">Updating demo video via the web</h3>
<p>
The RetailDemo app in <code>/packages/apps/RetailDemo</code> has the ability to
update the demo video if there is network connectivity. The URL to download the
video from can be configured by overriding the following string value in the
RetailDemo app:
</p>
<pre class="devsite-click-to-copy">
&lt;!-- URL where the retail demo video can be downloaded from. --&gt;
&lt;string name="retail_demo_video_download_url"&gt;&lt;/string&gt;
</pre>
<p>
If different videos need to be used in different regions, then different
download URLs can be configured by using locale-specific string resources
<code>res/values-*/strings.xml. </code>For example, if different videos need to
be used in the U.S. and the U.K., then corresponding download URLs can be placed
in <code>res/values-en-rUS/strings.xml</code> and
<code>res/values-en-rGB/strings.xml</code>, respectively.
</p>
<p>
In <code>res/values-en-rUS/strings.xml</code>:
</p>
<pre class="devsite-click-to-copy">
&lt;string name="retail_demo_video_download_url"&gt;download URL for US video goes here&lt;/string&gt;
</pre>
<p>
And similarly in <code>res/values-en-rGB/strings.xml</code>:
</p>
<pre class="devsite-click-to-copy">
&lt;string name="retail_demo_video_download_url"&gt;download URL for UK video goes here&lt;/string&gt;
</pre>
<p>
This video will be downloaded at most once per every device reboot. When the
video on the device is being played, RetailDemo app will check in the background
if the download URL is provided and the video at the URL is newer than the one
being played.
<p>
If so, RetailDemo app will download this video and start playing
it. Once this video is downloaded, the downloaded video will be used for playing
in the demo sessions going forward. None of the checks happen again until after
next reboot.
</p>
</body>
</html>