向 Android 添加新的像素格式

借助合集保持井井有条 根据您的偏好保存内容并对其进行分类。

添加到 Android 的所有新像素格式都必须包含在 Android 接口定义语言 (AIDL) 和 Android 硬件缓冲区 (AHB) 中。AIDL 和 AHB 对稳定性和标准化有严格的要求，因此在扩展功能时需要谨慎处理。所有新的像素格式都必须在 AOSP 中落实，并且所有更新都必须由 AIDL 和 AHB 专家单独确认。这种谨慎确认的过程是在平台上标准化任何新像素格式的重要因素。

本页概述了在 AOSP 上添加新像素格式所需的 AOSP 代码变更和流程。

在添加新的像素格式之前，请按照提交补丁中的概述下载源代码并上传补丁。

向 AIDL 添加新的像素格式

添加对新像素格式的支持需要同时更改 AIDL 中的两个 PixelFormat.aidl 文件。有关 AIDL 源代码，请参阅 hardware/interfaces/graphics/common/aidl/。

要向 AIDL 添加新的像素格式，请按照以下步骤操作：

1. 按照现有的代码约定，将新的像素格式作为新条目附加到 PixelFormat.aidl 中的 PixelFormat 枚举的末尾，并将您的条目的十六进制值设置为比上一个条目大 1。使您的代码更改与之前的条目相匹配。有关 RGBA_8888 像素格式条目的示例，请参阅以下内容：

   /**
    * 32-bit format that has 8-bit R, G, B, and A components, in that order,
    * from the lowest memory address to the highest memory address.
    *
    * The component values are unsigned normalized to the range [0, 1], whose
    * interpretation is defined by the dataspace.
    */
   RGBA_8888 = 0x1,
   

   在对 PixelFormat.aidl 进行更改后，当您构建代码时，会看到以下错误消息：

   android_developer:~/android/aosp-main: m
   ...
   ###############################################################################
   # ERROR: AIDL API change detected                                             #
   ###############################################################################
   Above AIDL file(s) has changed. Run `m android.hardware.graphics.common-update-api` to reflect the changes
   to the current version so that it is reviewed by
   android-aidl-api-council@google.com
   And then you need to change dependency on android.hardware.graphics.common-V(n)-* to android.hardware.graphics.common-V(n+1)-* to use
   new APIs.
   

2. 要清除此错误，请运行以下命令（如错误消息中所述）以更改 aidl_api 目录中的 PixelFormat.aidl：

   m android.hardware.graphics.common-update-api
   

   运行上述命令会更新正确的文件，以便能够正常构建。

向 AHB 添加新的像素格式

添加对新像素格式的支持需要更改 hardware_buffer.h 和 AHardwareBuffer.cpp。有关 AHB 源代码，请参阅 frameworks/native/libs/nativewindow。

要向 AHB 添加新的像素格式，请按照以下步骤操作：

1. 在 hardware_buffer.h 中，将新的像素格式作为新条目附加到 AHardwareBuffer_Format 枚举的末尾。遵循现有的代码约定。

   使用 RGBA_8888 像素格式示例，添加新的像素格式条目，如下所示：

   /**
    * Corresponding formats:
    *   Vulkan: VK_FORMAT_R8G8B8A8_UNORM
    *   OpenGL ES: GL_RGBA8
    */
   AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM = 1,
   

   请注意，新的像素格式在 AHB 中被赋予一个名称，该名称必须以 AHARDWAREBUFFER_FORMAT_ 开头，后跟通道缩写和位深度，并以编码结尾。此枚举条目必须具有与 PixelFormat.aidl 中相同的十六进制值。

   像素格式应具有关联的 Vulkan 或 OpenGL ES 格式之一或两者。在适当的位置指定关联的格式。如果不存在关联的格式，请指定 N/A。

2. 如果像素格式具有关联的 OpenGL ES 格式，则将其添加到 CTS 下的可选测试中。为此，请使用新的格式的 FORMAT_CASE(...) 和 GL_FORMAT_CASE(...) 将新的 GL 格式添加到 AHBFormatAsString(int32_t format) 中的 AHardwareBufferGLTest.cpp 中，如下所示：

   const char* AHBFormatAsString(int32_t format) {
     switch (format) {
         ...
         FORMAT_CASE(R8G8B8A8_UNORM);
         ...
         GL_FORMAT_CASE(GL_RGB8);
     }
     return "";
   }
   

3. 接下来，向 AHardwareBufferGLTest.cpp 添加一个新测试，如下所示：

   class RGBA8Test : public AHardwareBufferGLTest {};
   
   // Verify that if we can allocate an RGBA8 AHB we can render to it.
   TEST_P(RGBA8Test, Write) {
       AHardwareBuffer_Desc desc = GetParam();
       desc.usage = AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER;
       if (!SetUpBuffer(desc)) {
           return;
       }
   
       ASSERT_NO_FATAL_FAILURE(SetUpFramebuffer(desc.width, desc.height, 0, kBufferAsRenderbuffer));
       ASSERT_NO_FATAL_FAILURE(
           SetUpProgram(kVertexShader, kColorFragmentShader, kPyramidPositions, 0.5f));
   
       glDrawArrays(GL_TRIANGLES, 0, kPyramidVertexCount);
       ASSERT_EQ(GLenum{GL_NO_ERROR}, glGetError());
   }
   
   INSTANTIATE_TEST_CASE_P(
       SingleLayer, RGBA8Test,
       ::testing::Values(
           AHardwareBuffer_Desc{57, 33, 1, AHARDWAREBUFFER_FORMAT_R16G16_UINT, 0, 0, 0, 0}),
       &GetTestName);
   

   至少指定一组 AHardwareBuffer_Desc 值。如果需要，添加更多值。

4. 在 AHardwareBuffer.cpp 中，找到静态断言的结尾，它们位于

   // ----------------------------------------------------------------------------
   // Validate hardware_buffer.h and PixelFormat.aidl agree
   // ----------------------------------------------------------------------------
   

   添加一个新的 static_assert 用于新的像素格式，使用 PixelFormat:: 枚举，而不是 HAL_PIXEL_FORMAT 常量。使用 向 AIDL 添加新的像素格式 中 RGBA_8888 像素格式的相同示例，按如下方式添加新的像素格式条目

   static_assert(static_cast(aidl::android::hardware::graphics::common::PixelFormat::RGBA_8888) ==
     AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM,
   "HAL and AHardwareBuffer pixel format don't match");
   

5. 通过将新的像素格式附加到 AHardwareBufferTest.cpp 中的 PrintAhbFormat() 的末尾，将新的像素格式添加到相应的测试中。遵循现有的代码约定，如下所示

   void PrintAhbFormat(std::ostream& os, uint64_t format) {
       switch (format) {
           ...
           FORMAT_CASE(R8G8B8A8_UNORM);
           default: os << "unknown"; break;
       }
   }
   

6. 通过将新条目附加到 @IntDef，将新的像素格式添加到 HardwareBuffer.java 中的 HardwareBuffer SDK 中。例如，RGBA_8888 格式的条目显示如下

   @Retention(RetentionPolicy.SOURCE)
   @IntDef(prefix = { "RGB", "BLOB", "YCBCR_", "D_", "DS_", "S_" }, value = {
     ...
     RGBA_8888,
   })
   

   如果组件值不是无符号归一化值，则在变量名称中显式指示该值。例如，仅用于无符号整数 16 位红色通道格式的变量名称必须为 R_16UI，而具有附加的无符号整数 16 位绿色通道格式的相同格式必须为 RG_16UI16UI。

7. 通过在 HardwareBuffer.java 中将新的像素格式添加为 static int，方法是在 @Format 的末尾附加一个新的公共成员变量

   @Format
   ...
   /** Format: 8 bits each red, green, blue, alpha */
   public static final int RGBA_8888 = 0x1;
   

   此枚举条目必须具有与 PixelFormat.aidl 和 hardware_buffer.h 中的十六进制值相同的值。遵循现有约定。

8. 尝试使用这些代码更改进行构建会生成构建错误

   android_developer:~/android/aosp-main: m
   ...
   ******************************
   You have tried to change the API from what has been previously approved.
   
   To make these errors go away, you have two choices:
      1. You can add '@hide' javadoc comments (and remove @SystemApi/@TestApi/etc)
         to the new methods, etc. shown in the above diff.
   
      2. You can update current.txt and/or removed.txt by executing the following command:
            m api-stubs-docs-non-updatable-update-current-api
   
         To submit the revised current.txt to the main Android repository,
         you will need approval.
   ******************************
   ...
   

   要清除此错误，请运行错误消息中指定的以下命令，以更改 current.txt

   m api-stubs-docs-non-updatable-update-current-api
   

   运行上述命令会更新正确的文件，以便能够正常构建。

9. 通过将新的像素格式附加到 HardwareBufferTest.java 中的 paramsForTestCreateOptionalFormats() 的末尾，将新的像素格式添加到 Java 测试中，如下所示

   private static Object[] paramsForTestCreateOptionalFormats() {
     return new Integer[]{
         HardwareBuffer.RGBA_8888
     };
   

向窗口系统集成添加新的像素格式

要将新的像素格式用作图形 API 中帧缓冲区的格式，请将其添加到相关图形 API 的相应窗口系统集成 (WSI) 中。对于使用 Vulkan API 的应用或系统进程，请更新 Vulkan 交换链。对于使用 OpenGL ES API 的应用或系统进程，请更新 EGL API。

新像素格式的 Vulkan WSI 更改

按如下方式更新 Vulkan WSI

1. 在 swapchain.cpp 中的 GetNativePixelFormat(VkFormat format) 函数中添加新的 case

   android::PixelFormat GetNativePixelFormat(VkFormat format) {
     ...
     switch (format) {
         ...
         case VK_FORMAT_R8G8B8A8_UNORM:
             native_format = PixelFormat::RGBA_8888;
             break;
         ...
         default:
             ALOGV("unsupported swapchain format %d", format);
             break;
     }
     return native_format;
   }
   

2. 如果像素格式需要 Vulkan 扩展才能运行，请查询 Vulkan 扩展。对于实例端扩展，请使用 instance_data，如下所示

   bool colorspace_ext = instance_data.hook_extensions.test(ProcHook::EXT_swapchain_colorspace);
   

   对于设备端扩展，请使用以下内容

   bool rgba10x6_formats_ext = false;
   uint32_t exts_count;
   const auto& driver = GetData(pdev).driver;
   driver.EnumerateDeviceExtensionProperties(pdev, nullptr, &exts_count,
                                             nullptr);
   std::vector props(exts_count);
   driver.EnumerateDeviceExtensionProperties(pdev, nullptr, &exts_count,
                                             props.data());
   for (uint32_t i = 0; i < exts_count; i++) {
       VkExtensionProperties prop = props[i];
       if (strcmp(prop.extensionName,
                  VK_EXT_RGBA10X6_FORMATS_EXTENSION_NAME) == 0) {
           rgba10x6_formats_ext = true;
       }
   }
   

   Google 处理将实例或设备扩展公开给 swapchain.cpp 所需的基础架构。初始更改列表不需要从 Vulkan 加载程序正确设置扩展。

3. 接下来，枚举格式和颜色空间对

   desc.format = AHARDWAREBUFFER_FORMAT_R10G10B10A10_UNORM;
   if (AHardwareBuffer_isSupported(&desc) && rgba10x6_formats_ext) {
     all_formats.emplace_back(
         VkSurfaceFormatKHR{VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16,
                            VK_COLOR_SPACE_SRGB_NONLINEAR_KHR});
     if (colorspace_ext) {
       all_formats.emplace_back(
           VkSurfaceFormatKHR{VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16,
                              VK_COLOR_SPACE_PASS_THROUGH_EXT});
       all_formats.emplace_back(
           VkSurfaceFormatKHR{VK_FORMAT_R10X6G10X6B10X6A10X6_UNORM_4PACK16,
                              VK_COLOR_SPACE_DISPLAY_P3_NONLINEAR_EXT});
   }
   

   您必须了解兼容的格式和颜色空间对。

4. 将新格式添加到位于 external/deqp 的 dEQP-VK。
5. 通过从现有源代码推断所需的更改或联系您的 Android 支持以获取信息，更新 vktApiExternalMemoryTests.cpp 和 vktExternalMemoryUtil.cpp 中的 Vulkan 一致性测试。

新像素格式的 EGL 更改

按如下方式更新 EGL

1. 在 getNativePixelFormat() 函数中，修改 if-else 树以返回新像素格式的 AIDL 枚举。使用 RGBA_8888 像素格式的示例

   if (a == 0) {
     ...
   } else {
     if (componentType == EGL_COLOR_COMPONENT_TYPE_FIXED_EXT) {
         if (colorDepth > 24) {
             ...
         } else {
             *format = PixelFormat::RGBA_8888;
         }
     } else {
       ...
     }
   }
   

2. 要将新格式添加到 dEQP，请向 androidFormats 枚举添加新条目，如下所示

   static const GLenum androidFormats[] =
   {
     ...
     GL_RGBA8,
     ...
   };
   

提交您的更新

按照 贡献者指南 启动您的更改列表并与相应的团队分享。