Add a more detailed HAL for DISPLAY_DECORATION

Different hardware may prefer different formats for DISPLAY_DECORATION
layers. Add a new struct with two enums: one for the format, and one for
how to interpret the alpha. These two properties are orthogonal.

Add IComposerClient.getDisplayDecorationSupport for retrieving the
struct. I0c2fbc78cf5e4e97cede4762699a1ecc98620919 demonstrates a sample
implementation.

Remove the DisplayCapability.DISPLAY_DECORATION, which is replaced by
this.

Bug: 216644902
Test: manual
Change-Id: I27f119f927b23052c5fd8f068cbca75338fe7b91

graphics/common/aidl/aidl_api/android.hardware.graphics.common/current/android/hardware/graphics/common/AlphaInterpretation.aidl

@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) 2022, 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.
+ */
+///////////////////////////////////////////////////////////////////////////////
+// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE.                          //
+///////////////////////////////////////////////////////////////////////////////
+
+// This file is a snapshot of an AIDL file. Do not edit it manually. There are
+// two cases:
+// 1). this is a frozen version file - do not edit this in any case.
+// 2). this is a 'current' file. If you make a backwards compatible change to
+//     the interface (from the latest frozen version), the build system will
+//     prompt you to update this file with `m <name>-update-api`.
+//
+// You must not make a backward incompatible change to any AIDL file built
+// with the aidl_interface module type with versions property set. The module
+// type is used to build AIDL files in a way that they can be used across
+// independently updatable components of the system. If a device is shipped
+// with such a backward incompatible change, it has a high risk of breaking
+// later when a module using the interface is updated, e.g., Mainline modules.
+
+package android.hardware.graphics.common;
+/* @hide */
+@Backing(type="int") @VintfStability
+enum AlphaInterpretation {
+  COVERAGE = 0,
+  MASK = 1,
+}

graphics/common/aidl/aidl_api/android.hardware.graphics.common/current/android/hardware/graphics/common/DisplayDecorationSupport.aidl

@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) 2022, 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.
+ */
+///////////////////////////////////////////////////////////////////////////////
+// THIS FILE IS IMMUTABLE. DO NOT EDIT IN ANY CASE.                          //
+///////////////////////////////////////////////////////////////////////////////
+
+// This file is a snapshot of an AIDL file. Do not edit it manually. There are
+// two cases:
+// 1). this is a frozen version file - do not edit this in any case.
+// 2). this is a 'current' file. If you make a backwards compatible change to
+//     the interface (from the latest frozen version), the build system will
+//     prompt you to update this file with `m <name>-update-api`.
+//
+// You must not make a backward incompatible change to any AIDL file built
+// with the aidl_interface module type with versions property set. The module
+// type is used to build AIDL files in a way that they can be used across
+// independently updatable components of the system. If a device is shipped
+// with such a backward incompatible change, it has a high risk of breaking
+// later when a module using the interface is updated, e.g., Mainline modules.
+
+package android.hardware.graphics.common;
+/* @hide */
+@VintfStability
+parcelable DisplayDecorationSupport {
+  android.hardware.graphics.common.PixelFormat format;
+  android.hardware.graphics.common.AlphaInterpretation alphaInterpretation;
+}

graphics/common/aidl/android/hardware/graphics/common/AlphaInterpretation.aidl

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2022, 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.
+ */
+
+package android.hardware.graphics.common;
+
+/**
+ * How to interperet alpha values when it may be ambiguous.
+ * @hide
+ */
+@VintfStability
+@Backing(type="int")
+enum AlphaInterpretation {
+    /**
+     * Alpha values are treated as coverage.
+     *
+     * Pixels in the buffer with an alpha of 0 (transparent) will be rendered in
+     * black, and pixels with a max value will show the content underneath. An
+     * alpha in between will show the content blended with black.
+     */
+    COVERAGE = 0,
+    /**
+     * Alpha values are treated as a mask.
+     *
+     * Pixels in the buffer with an alpha of 0 (transparent) will show the
+     * content underneath, and pixels with a max value will be rendered in
+     * black. An alpha in between will show the content blended with black.
+     */
+    MASK = 1,
+}

graphics/common/aidl/android/hardware/graphics/common/DisplayDecorationSupport.aidl

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2022, 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.
+ */
+
+package android.hardware.graphics.common;
+
+import android.hardware.graphics.common.PixelFormat;
+import android.hardware.graphics.common.AlphaInterpretation;
+
+/**
+ * A description of how a device supports Composition.DISPLAY_DECORATION.
+ *
+ * If the device supports Composition.DISPLAY_DECORATION, a call to
+ * IComposerClient.getDisplayDecorationSupport should return an instance of this
+ * parcelable. Otherwise the method should return null.
+ * @hide
+ */
+@VintfStability
+parcelable DisplayDecorationSupport {
+    /**
+     * The format to use for DISPLAY_DECORATION layers. Other formats are not
+     * supported. If other formats are used with DISPLAY_DECORATION, the result
+     * is undefined.
+     */
+    PixelFormat format;
+    /**
+     * How the device intreprets the alpha in the pixel buffer.
+     */
+    AlphaInterpretation alphaInterpretation;
+}

graphics/composer/aidl/aidl_api/android.hardware.graphics.composer3/current/android/hardware/graphics/composer3/DisplayCapability.aidl

@@ -41,6 +41,5 @@ enum DisplayCapability {
   PROTECTED_CONTENTS = 4,
   AUTO_LOW_LATENCY_MODE = 5,
   SUSPEND = 6,
-  DISPLAY_DECORATION = 7,
-  DISPLAY_IDLE_TIMER = 8,
+  DISPLAY_IDLE_TIMER = 7,
 }

graphics/composer/aidl/aidl_api/android.hardware.graphics.composer3/current/android/hardware/graphics/composer3/IComposerClient.aidl

@@ -59,6 +59,7 @@ interface IComposerClient {
   @nullable ParcelFileDescriptor getReadbackBufferFence(long display);
   android.hardware.graphics.composer3.RenderIntent[] getRenderIntents(long display, android.hardware.graphics.composer3.ColorMode mode);
   android.hardware.graphics.composer3.ContentType[] getSupportedContentTypes(long display);
+  @nullable android.hardware.graphics.common.DisplayDecorationSupport getDisplayDecorationSupport(long display);
   void registerCallback(in android.hardware.graphics.composer3.IComposerCallback callback);
   void setActiveConfig(long display, int config);
   android.hardware.graphics.composer3.VsyncPeriodChangeTimeline setActiveConfigWithConstraints(long display, int config, in android.hardware.graphics.composer3.VsyncPeriodChangeConstraints vsyncPeriodChangeConstraints);

graphics/composer/aidl/android/hardware/graphics/composer3/Composition.aidl

@@ -75,13 +75,12 @@ enum Composition {
     SIDEBAND = 5,
     /**
      * A display decoration layer contains a buffer which is used to provide
-     * anti-aliasing on the cutout region/rounded corners on the top and
+     * anti-aliasing on the cutout region and rounded corners on the top and
      * bottom of a display.
      *
-     * Pixels in the buffer with an alpha of 0 (transparent) will show the
-     * content underneath, and pixels with a max alpha value will be rendered in
-     * black. An alpha in between will show the underlying content blended with
-     * black.
+     * Only supported if the device returns a valid struct from
+     * getDisplayDecorationSupport. Pixels in the buffer are interpreted
+     * according to the DisplayDecorationSupport.alphInterpretation.
      *
      * Upon validateDisplay, the device may request a change from this type
      * to either DEVICE or CLIENT.

graphics/composer/aidl/android/hardware/graphics/composer3/DisplayCapability.aidl

@@ -75,13 +75,9 @@ enum DisplayCapability {
      * PowerMode.ON_SUSPEND and PowerMode.DOZE_SUSPEND must be supported.
      */
     SUSPEND = 6,
-    /**
-     * Indicates that the display supports Composition.DISPLAY_DECORATION.
-     */
-    DISPLAY_DECORATION = 7,
     /**
      * Indicates that the display supports IComposerClient.setIdleTimerEnabled and
      * IComposerCallback.onVsyncIdle.
      */
-    DISPLAY_IDLE_TIMER = 8,
+    DISPLAY_IDLE_TIMER = 7,
 }

graphics/composer/aidl/android/hardware/graphics/composer3/IComposerClient.aidl

@@ -16,6 +16,7 @@
 
 package android.hardware.graphics.composer3;
 
+import android.hardware.graphics.common.DisplayDecorationSupport;
 import android.hardware.graphics.common.Transform;
 import android.hardware.graphics.composer3.ClientTargetProperty;
 import android.hardware.graphics.composer3.ColorMode;
@@ -515,6 +516,16 @@ interface IComposerClient {
      */
     ContentType[] getSupportedContentTypes(long display);
 
+    /**
+     * Report whether and how this display supports Composition.DISPLAY_DECORATION.
+     *
+     * @return A description of how the display supports DISPLAY_DECORATION, or null
+     * if it is unsupported.
+     *
+     * @exception EX_BAD_DISPLAY when an invalid display handle was passed in.
+     */
+    @nullable DisplayDecorationSupport getDisplayDecorationSupport(long display);
+
     /**
      * Provides a IComposerCallback object for the device to call.
      *