Car display compatibility

Car display compatibility enables phone and tablet apps to perform well on automotive devices.

Features include:

• DPI scaling: Scale app UI elements based on display DPI.
• Safe area for app rendering: Contain app content within a safe area, avoiding obscuration by system UI elements.
• App classification logic: Identify apps that require Car Display Compat.

Compatibility features

The platform provides several mechanisms to optimize app rendering and scaling on automotive displays.

DPI scaling

The DPI scaling feature enables device makers to scale the density DPI of individual apps or all apps that require Car Display Compat.

To configure the density scaling of apps:

1. Add a config file /product/etc/display_compat_config.xml:

   <?xml version="1.0" encoding="utf-8"?>
   <!--
       Each scale factor can have the following attributes
   
       display     (required) Specifies the displayId to which this scale factor will be applied.
       packageName (optional) Specifies the packageName to which the scale factor will be applied.
                   If omitted, the scaling will apply to all packages.
   
       For example:
       <scale display="0" packageName="com.android.car.media.localmediaplayer">0.5</scale>
   
       This means that only package `com.android.car.media.localmediaplayer` on display `0` will be scaled.
   -->
   <config>
   <scale display="0">1.0</scale>
   </config>
   

2. To set a default scale value for all apps that require Car Display Compat, change the default scale for display 0 to <scale display="0">1.0</scale>. The value is the inverse scale value. For example, to scale apps that require Car Display Compat to 1.5x, set the scale value to (1 / 1.5) = 0.67:

   <config>
       <scale display="0">0.67</scale>
   </config>
   

3. To set a scale value for a specific app, add a new scale element to the config. In this example, YouTube Automotive is scaled to 1.43x (for example, (1 / 1.43) = 0.7).

   <config>
       <scale display="0">0.67</scale>
       <scale display="0" packageName="com.google.android.apps.automotive.youtube">0.7</scale>
   </config>
   

If the system was running when you changed /product/etc/display_compat_config.xml, you must clear the cache for the new config to take effect. Use this macro to clear the cache:

SECURE_SETTING_KEY="android.software.car.display_compatibility:settings:secure"
USER_ID_LIST=$(adb shell cmd user list -v | grep 'id=' | cut -d'=' -f2 | cut -d',' -f1)
for USER_ID in $USER_ID_LIST; do
    echo "Deleting Display Compat config for user: $USER_ID"
    adb shell settings delete secure --user $USER_ID $SECURE_SETTING_KEY
    sleep 1
    echo
done

1. Add the config file and feature declaration to an AAOS build, for example, in vendor/OEM_NAME/products/displaycompat:

   # File: vendor/OEM_NAME/products/displaycompat/Android.bp
   
   prebuilt_etc {
       name: "display_compat_config",
       filename: "display_compat_config.xml",
       src: "display_compat_config.xml",
       product_specific: true,
   }
   

Safe app area

Phone and tablet apps often aren't designed for the large system bars found in Automotive. These apps must be restricted from drawing content beneath system bars or system overlays. Otherwise, they might render interactive elements in an area obscured from the end user.

The safe app area is implemented using Scalable UI SafeBounds.

App classification logic

You can use CarPackageManager.requiresDisplayCompat(..) to build additional functionality that enhances app compatibility. For example, you can use this functionality to add a back button or additional UI.

App developers can opt in to car display compatibility by including metadata in the app's manifest:

<meta-data
    android:name="android.software.car.display_compatibility"
    android:value="true" />

The system evaluates whether an app requires car display compatibility features using the following logic (evaluated in order):

1. Manifest metadata android.software.car.display_compatibility:
   • If android:value="true" → App requires compat
   • If android:value="false" → App doesn't require compat
   • If metadata is missing, proceed to the next check.
2. Uses feature android.hardware.type.automotive:
   • If the feature is declared (irrespective of whether android:required is true or false) → App doesn't require compat
   • If the feature is missing, proceed to the next check.
3. App activities:
   • If the app has no activities (such as RROs, headless apps, or services) → App doesn't require compat
   • If the app has activities, proceed to the next check.
4. Application info:
   • If the app is privileged → App doesn't require compat
   • If the app is a system app (FLAG_SYSTEM) → App doesn't require compat
   • Otherwise, proceed to the next check.
5. Signature info:
   • If the app is platform-signed (signed with the same signature as the Android framework) → App doesn't require compat
   • Otherwise, proceed to the next check.
6. Fallback decision:
   • If all checks pass without opting out → App requires compat

See CarDisplayCompatScaleProviderUpdatableImpl.requiresDisplayCompatNotCachedLocked.

Device support

Devices that support car display compatibility must declare support using the feature declaration:

<feature name="android.software.car.display_compatibility" />