AIDL for Hardware Composer HAL

Starting in Android 13, the Hardware Composer (HWC) HAL is defined in AIDL and the HIDL versions ranging from android.hardware.graphics.composer@2.1 to android.hardware.graphics.composer@2.4 are deprecated.

This page describes the differences between the AIDL and the HIDL HAL for the HWC and the implementation and testing of the AIDL HAL.

Because of the advantages offered by AIDL, vendors are encouraged to implement the AIDL composer HAL starting Android 13 instead of the HIDL version. See the Implementation section for more information.

Differences between AIDL and HIDL HALs

The new AIDL composer HAL, named android.hardware.graphics.composer3, is defined in IComposer.aidl. It exposes an API similar to the HIDL HAL android.hardware.graphics.composer@2.4 with the following changes:

  • Removal of the Fast Message Queue (FMQ) in favor of parcelable commands.

    The AIDL HAL defines the command interface based on strongly typed parcelable types as opposed to the serialized commands over FMQ in HIDL. This provides a stable interface for commands and a more readable definition of how the command payload is interpreted.

    The executeCommands method is defined in IComposerClient.aidl as

    CommandResultPayload[] executeCommands(in DisplayCommand[] commands);

    where each command is a strongly typed parcelable type defined in DisplayCommand.aidl. Command responses are strongly typed parcelables defined in CommandResultPayload.aidl.

  • Removal of IComposerClient.getClientTargetSupport as there are no active clients for this method.

  • Representation of colors as floats instead of bytes to better align with the upper graphics stack in Android as defined in ASurfaceTransaction_setColor.

  • Addition of new fields for controlling HDR content.

    In the AIDL HAL, mixed SDR/HDR layer stacks support the seamless dimming of SDR layers when an HDR layer is simultaneously on screen.

    The brightness field in LayerCommand lets SurfaceFlinger specify a per-layer brightness, so that the HWC dims the layer’s content in linear light space, as opposed to gamma space.

    The brightness field in ClientTargetPropertyWithBrightness lets the HWC specify the brightness space for client composition and to instruct RenderEngine whether to dim SDR layers in client composition.

    The dimmingStage field lets the HWC configure when RenderEngine should dim content. This accommodates vendor-defined ColorModes, which might prefer to dim in gamma space, to allow vendor-defined contrast enhancements in their color pipelines.

  • Addition of a new composition type DISPLAY_DECORATION in Composition.aidl for screen decorations.

    Some devices have dedicated hardware to optimize drawing the alpha mask that smooths rounded corners and cutouts on displays. Devices with such hardware must implement IComposerClient.getDisplayDecorationSupport to return a DisplayDecorationSupport structure as defined in the new DisplayDecorationSupport.aidl. This structure describes the PixelFormat and AlphaInterpretation enums required by the device. Upon this implementation, System UI marks the alpha mask layer as DISPLAY_DECORATION, a new composition type that takes advantage of the dedicated hardware.

  • Addition of a new expectedPresentTime field to DisplayCommand.aidl.

    The expectedPresentTime field lets SurfaceFlinger set the expected present time to when the current content must be displayed on screen. With this feature, SurfaceFlinger sends a present command to the implementation ahead of time, allowing it to pipeline more of the composition work.

  • Addition of new APIs to control boot display configuration.

    Using BOOT_DISPLAY_CONFIG, vendors can specify that the boot display configuration is supported. The setBootDisplayConfig, clearBootDisplayConfig, and getPreferredBootDisplayConfig methods use BOOT_DISPLAY_CONFIG as follows:

    • Using setBootDisplayConfig, the framework informs vendors of the boot time display configuration. Vendors must cache in the boot display configuration, and boot in this config on next reboot. If the device is unable to boot in this config, the vendor must find a config that matches the resolution and refresh rate of this config. If no such config exists, the vendor should use their preferred display config.

    • Using clearBootDisplayConfig, the framework informs the vendors to clear the boot display configuration, and boot in their preferred display config during the next reboot.

    • Using getPreferredBootDisplayConfig, the framework queries the vendor's preferred boot mode.

    When the boot display configuration isn't supported, these methods return a value of UNSUPPORTED.

  • Addition of new APIs to control the display idle timer.

    • Using DISPLAY_IDLE_TIMER, vendors can specify that an inactivity timer is implemented by the vendor for this display. When idle, this capability changes the refresh rate to a lower setting to preserve power. The platform uses setIdleTimerEnabled to control the timeout of the timer, and in some cases, to disable it in order to prevent undesired refresh rate switches when idle.

    • Using the IComposerCallback.onVsyncIdle callback indicates to the platform that the display is idle and the vsync cadence has changed. The platform responds to this callback by resetting its vsync model. It forces a vsync resync on the next frame, and learns the new vsync cadence.

Implementation

Vendors aren't required to implement the AIDL HAL for Android 13. However, they're encouraged to implement the AIDL composer HAL instead of the HIDL version to use the new functionality and APIs.

A reference implementation for the AIDL HWC HAL is implemented in Android emulators.

Testing

To test your implementation, run VtsHalGraphicsComposer3_TargetTest.