自 2025 年 3 月 27 日起，我們建議您使用 android-latest-release 而非 aosp-main 建構及貢獻 AOSP。詳情請參閱「Android 開放原始碼計畫變更」。

本頁面由 Cloud Translation API 翻譯而成。

在 Android 中新增像素格式

所有新增至 Android 的像素格式都必須納入 Android 介面定義語言 (AIDL) 和 Android 硬體緩衝區 (AHB)。AIDL 和 AHB 都有嚴格的穩定性和標準化要求，因此擴充功能時必須謹慎處理。所有新的像素格式都必須納入 AOSP，且所有更新都必須由 AIDL 和 AHB 專家個別確認。仔細確認的程序是平台標準化任何新像素格式的重要因素。

本頁面說明在 Android 開放原始碼計畫 (AOSP) 中新增像素格式時，必須進行的 AOSP 程式碼變更和必要程序。

新增像素格式前，請先下載來源並上傳修補程式，如「提交修補程式」一文所述。

在 AIDL 中新增像素格式

如要新增對新像素格式的支援，必須變更 AIDL 內的兩個 PixelFormat.aidl 檔案。如需 AIDL 原始碼，請參閱 hardware/interfaces/graphics/common/aidl/。

如要將新的像素格式新增至 AIDL，請按照下列步驟操作：

按照現有程式碼慣例，在 PixelFormat.aidl 的 PixelFormat 列舉結尾新增像素格式，並將項目的十六進位值設為比前一個項目多一。將程式碼變更與先前的項目比對。請參閱以下範例，瞭解 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-android-latest-release: 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.

如要清除這項錯誤，請按照錯誤訊息中的指示執行下列指令，變更 aidl_api 目錄中的 PixelFormat.aidl：
```
m android.hardware.graphics.common-update-api
```
執行上述指令後，系統會更新正確的檔案，讓您正常建構。

注意：請勿嘗試手動編輯這個檔案。

在 AHB 中新增像素格式

如要新增對新像素格式的支援，必須變更 hardware_buffer.h 和 AHardwareBuffer.cpp。如需 AHB 原始碼，請參閱 frameworks/native/libs/nativewindow。

如要在 AHB 中新增正式像素，請按照下列步驟操作：

在 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。
如果像素格式有相關聯的 OpenGL ES 格式，請將該格式新增至 CTS 下的選用測試。如要這麼做，請將新的 GL 格式新增至 AHBFormatAsString(int32_t format) 中的 AHardwareBufferGLTest.cpp，並使用 FORMAT_CASE(...) 和 GL_FORMAT_CASE(...) 顯示新格式，如下所示：
```
const char* AHBFormatAsString(int32_t format) {
  switch (format) {
      ...
      FORMAT_CASE(R8G8B8A8_UNORM);
      ...
      GL_FORMAT_CASE(GL_RGB8);
  }
  return "";
}
```

接著，將新測試新增至 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 值。視需要新增更多值。

在 AHardwareBuffer.cpp 中，找出靜態斷言的結尾：

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

使用 PixelFormat:: 列舉，而非 HAL_PIXEL_FORMAT 常數，為新的像素格式附加新的 static_assert。以在 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");

將新的像素格式附加至 AHardwareBufferTest.cpp 中 PrintAhbFormat() 的結尾，將新的像素格式新增至適當的測試。請遵循現有的程式碼慣例，如下所示：
```
void PrintAhbFormat(std::ostream& os, uint64_t format) {
    switch (format) {
        ...
        FORMAT_CASE(R8G8B8A8_UNORM);
        default: os << "unknown"; break;
    }
}
```
在 HardwareBuffer.java 中，將新的像素格式新增至 HardwareBuffer SDK：在 @IntDef 中附加新項目。舉例來說，RGBA_8888 格式的項目如下所示：
```
@Retention(RetentionPolicy.SOURCE)
@IntDef(prefix = { "RGB", "BLOB", "YCBCR_", "D_", "DS_", "S_" }, value = {
  ...
  RGBA_8888,
})
```
如果元件值不是未簽署的正規化值，請在變數名稱中明確指出值。舉例來說，無正負號整數 16 位元紅色通道專用格式的變數名稱必須是 R_16UI，而相同格式加上無正負號整數 16 位元綠色通道格式的變數名稱必須是 RG_16UI16UI。
將新的像素格式新增為 static int，方法是在 @Format 結尾附加新的公開成員變數：HardwareBuffer.java
```
@Format
...
/** Format: 8 bits each red, green, blue, alpha */
public static final int RGBA_8888 = 0x1;
```
這個列舉項目必須與 PixelFormat.aidl 和 hardware_buffer.h 的十六進位值相同。遵循現有慣例。

嘗試使用這些程式碼變更進行建構時，會產生建構錯誤：

android_developer:~/android/aosp-android-latest-release: 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

執行上述指令後，系統會更新正確的檔案，讓您正常建構。

將新的像素格式附加至 HardwareBufferTest.java 中的 paramsForTestCreateOptionalFormats() 結尾，將新的像素格式新增至 Java 測試，如下所示：
```
private static Object[] paramsForTestCreateOptionalFormats() {
  return new Integer[]{
      HardwareBuffer.RGBA_8888
  };
```

在 Window System 整合中新增像素格式

如要將新的像素格式做為繪圖 API 中 Framebuffer 的格式，請將其新增至相關繪圖 API 的適當視窗系統整合 (WSI)。如果應用程式或系統程序使用 Vulkan API，請更新 Vulkan Swapchain。如果應用程式或系統程序使用 OpenGL ES API，請更新 EGL API。

新 Pixel 格式的 Vulkan WSI 變更

請按照下列步驟更新 Vulkan WSI：

在 swapchain.cpp 中，將新案例新增至 GetNativePixelFormat(VkFormat format) 函式：

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;
}

如果像素格式需要 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 載入器正確設定擴充功能。

接著，列舉格式和色彩空間配對：

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});
}

您必須瞭解相容的格式和色彩空間組合。

將新格式新增至 dEQP-VK (位於 external/deqp)。
在 vktApiExternalMemoryTests.cpp 和 vktExternalMemoryUtil.cpp 中更新 Vulkan 一致性測試，方法是從現有來源推斷必要變更，或向 Android 支援團隊詢問相關資訊。

新像素格式的 EGL 變更

將 EGL 更新為下列內容：

在 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 {
    ...
  }
}

如要將新格式新增至 dEQP，請在 androidFormats 列舉中新增項目，如下所示：
```
static const GLenum androidFormats[] =
{
  ...
  GL_RGBA8,
  ...
};
```

提交更新

請按照「適用於貢獻者」一節的說明，建立變更清單並與適當的團隊分享。