AIDL for Hardware Composer HAL

Starting in Android 13, the Hardware Composer (HWC) HAL is defined in AIDL. 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 HIDL HALs for the HWC, and how to implement and test the AIDL HAL.

Because AIDL offers advantages, vendors can implement the AIDL composer HAL starting in Android 13 instead of the HIDL version. For more information, see the Implementation section.

Differences between AIDL and HIDL HALs

The new AIDL composer HAL, named android.hardware.graphics.composer3, is defined in IComposer.aidl. The API is similar to the HIDL HAL android.hardware.graphics.composer@2.4, but includes 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 instead of the serialized commands over FMQ in HIDL. This provides a stable interface for commands and a more readable definition of how the system interprets the command payload.

    The executeCommands 5 method is defined in IComposerClient.aidl:

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

    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 because no active clients use this method.

  • Representation of colors as floats instead of bytes to align with the upper graphics stack in Android, as defined by 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 on screen at the same time.

    The brightness field in LayerCommand lets SurfaceFlinger specify a per-layer brightness. This enables the HWC to dim the layer's content in linear light space instead of gamma space.

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

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

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

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

  • Addition of an expectedPresentTime field to DisplayCommand.aidl.

    The expectedPresentTime field lets SurfaceFlinger set the expected present time for when the current content must be displayed on screen. With this feature, SurfaceFlinger sends a present command to the implementation ahead of time, which allows 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 must 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, vendors are encouraged to implement the AIDL composer HAL instead of the HIDL version to use the functionality and APIs of the AIDL composer HAL.

Android emulators include a reference implementation for the AIDL HWC HAL.

Testing

To test your implementation, run VtsHalGraphicsComposer3_TargetTest.