เพิ่มรูปแบบพิกเซลใหม่ลงใน Android

รูปแบบพิกเซลใหม่ทั้งหมดที่เพิ่มลงใน Android ต้องรวมอยู่ใน Android Interface Definition Language (AIDL) และ Android Hardware Buffer (AHB) AIDL และ AHB มีข้อกำหนดเกี่ยวกับความเสถียรและมาตรฐานที่เข้มงวด ซึ่งจำเป็นต้องมี ขั้นตอนอย่างละเอียดเมื่อขยายฟังก์ชันการทำงาน รูปแบบพิกเซลใหม่ทั้งหมดต้องอยู่ใน AOSP และผู้เชี่ยวชาญ AIDL และ AHB ต้องยืนยันการอัปเดตแต่ละรายการ กระบวนการยืนยันอย่างละเอียดรอบคอบนี้เป็นปัจจัยสําคัญในการกำหนดมาตรฐานรูปแบบพิกเซลใหม่บนแพลตฟอร์ม

หน้านี้จะอธิบายถึง AOSP ที่จำเป็น การเปลี่ยนแปลงโค้ดและขั้นตอนที่จำเป็นสำหรับการเพิ่มรูปแบบพิกเซลใหม่ใน AOSP

ก่อนเพิ่มรูปแบบพิกเซลใหม่ ให้ดาวน์โหลดแหล่งที่มาและอัปโหลดแพตช์ตามที่ระบุไว้ในหัวข้อการส่งแพตช์

เพิ่มรูปแบบพิกเซลใหม่ลงใน AIDL

การเพิ่มการรองรับรูปแบบพิกเซลใหม่ต้องมีการแก้ไขไฟล์ PixelFormat.aidl ทั้ง 2 ไฟล์ที่อยู่ใน AIDL ดูซอร์สโค้ด AIDL ได้ที่ hardware/interfaces/graphics/common/aidl/

หากต้องการเพิ่มรูปแบบพิกเซลใหม่ลงใน AIDL ให้ทําตามขั้นตอนต่อไปนี้

  1. เพิ่มรูปแบบพิกเซลใหม่เป็นรายการใหม่ต่อท้าย PixelFormat enum ใน PixelFormat.aidl โดยทำตามรูปแบบโค้ดที่มีอยู่และตั้งค่าเลขฐาน 16 สำหรับรายการให้มากกว่ารายการก่อนหน้า 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-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.

  2. หากต้องการล้างข้อผิดพลาดนี้ ให้เรียกใช้คําสั่งต่อไปนี้ตามที่ระบุไว้ในข้อความแสดงข้อผิดพลาดเพื่อเปลี่ยน PixelFormat.aidl ในไดเรกทอรี aidl_api

    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 enum ทำตามแบบแผนของโค้ดที่มีอยู่

    โดยใช้ตัวอย่างรูปแบบพิกเซล RGBA_8888 ให้เพิ่มรายการรูปแบบพิกเซลใหม่ดังนี้

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

    โปรดทราบว่ารูปแบบพิกเซลใหม่จะได้รับชื่อเป็น AHB ซึ่งต้องเริ่มต้นด้วย AHARDWAREBUFFER_FORMAT_ ตามด้วยตัวย่อของช่องและบิต และลงท้ายด้วยการเข้ารหัสด้วย รายการ Enum นี้ต้องมีค่าฐาน 16 เดียวกันกับใน PixelFormat.aidl

    รูปแบบพิกเซลควรมีการเชื่อมโยงอย่างใดอย่างหนึ่งหรือทั้ง 2 อย่าง Vulkan หรือ OpenGL ES ระบุรูปแบบที่เชื่อมโยงตามความเหมาะสม หากไม่มีรูปแบบที่เชื่อมโยง ให้ระบุ N/A

  2. เพิ่มรูปแบบพิกเซลในการทดสอบที่ไม่บังคับภายใต้ CTS หากมีรูปแบบ OpenGL ES ที่เชื่อมโยงกัน ในการดำเนินการ ให้เพิ่มรูปแบบ GL ใหม่ไปยัง AHardwareBufferGLTest.cpp ใน AHBFormatAsString(int32_t format) กับ FORMAT_CASE(...) และ GL_FORMAT_CASE(...) สำหรับรูปแบบใหม่ดังนี้

    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 อย่างน้อย 1 ชุด เพิ่มค่าอื่นๆ หากจำเป็น

  4. ใน AHardwareBuffer.cpp ให้ค้นหาจุดสิ้นสุดของการยืนยันแบบคงที่ที่พบใน:

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

    เพิ่ม static_assert ใหม่ต่อท้ายรูปแบบพิกเซลใหม่ โดยใช้ enum ของ PixelFormat:: และไม่ใช่ค่าคงที่ HAL_PIXEL_FORMAT โดยใช้ตัวอย่างเดียวกันสำหรับรูปแบบพิกเซล RGBA_8888 จากหัวข้อเพิ่มรูปแบบพิกเซลใหม่ลงใน AIDL ให้เพิ่มรายการรูปแบบพิกเซลใหม่ดังนี้

    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. เพิ่มรูปแบบพิกเซลใหม่ในการทดสอบที่เหมาะสมโดยใส่รูปแบบพิกเซลใหม่ต่อท้ายPrintAhbFormat()ในAHardwareBufferTest.cpp ปฏิบัติตามรูปแบบโค้ดที่มีอยู่ดังที่แสดงด้านล่าง

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

  6. เพิ่มรูปแบบพิกเซลใหม่ลงใน HardwareBuffer SDK ใน HardwareBuffer.java โดยเพิ่มรายการใหม่ต่อท้าย @IntDef ตัวอย่างเช่น รายการสำหรับรูปแบบ RGBA_8888 จะแสดงดังนี้

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

    หากค่าคอมโพเนนต์ไม่ได้เป็นค่าที่แปลงค่าโดยไม่นำเครื่องหมายบวกลบออก ให้ระบุค่าอย่างชัดเจนในชื่อตัวแปร เช่น ชื่อตัวแปรสําหรับแชแนลสีแดงแบบ 16 บิตที่เป็นจํานวนเต็มที่ไม่มีเครื่องหมาย รูปแบบเท่านั้นต้องเป็น R_16UI และอยู่ในรูปแบบเดียวกันโดยมีจำนวนเต็ม 16 บิตเพิ่มเติมที่ไม่มีการรับรอง รูปแบบช่องสีเขียวต้องเป็น RG_16UI16UI

  7. เพิ่มรูปแบบพิกเซลใหม่เป็น static int ใน HardwareBuffer.java, โดยเพิ่มตัวแปรสมาชิกสาธารณะใหม่ต่อท้าย @Format

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

    รายการ enum นี้ต้องมีค่าฐานสิบหกเหมือนกับ PixelFormat.aidl และ hardware_buffer.h ปฏิบัติตามแบบแผนที่มีอยู่

  8. การพยายามสร้างด้วยการเปลี่ยนแปลงโค้ดเหล่านี้จะทำให้เกิดข้อผิดพลาดในการสร้าง

    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

    การรันคําสั่งข้างต้นจะอัปเดตไฟล์ที่ถูกต้องเพื่อให้สร้างได้ตามปกติ

  9. เพิ่มรูปแบบพิกเซลใหม่ในการทดสอบ Java โดยใส่รูปแบบพิกเซลใหม่ต่อท้าย paramsForTestCreateOptionalFormats() ใน HardwareBufferTest.java ดังต่อไปนี้ 

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

เพิ่มรูปแบบพิกเซลใหม่ในการผสานรวมระบบหน้าต่าง

เพื่อใช้รูปแบบพิกเซลใหม่เป็นรูปแบบสำหรับเฟรมบัฟเฟอร์ใน Graphics API ใน Window System Integration (WSI) ที่เกี่ยวข้อง API กราฟิก สำหรับแอปหรือกระบวนการของระบบที่ใช้ Vulkan API ให้อัปเดต Vulkan Swapchain สําหรับแอปหรือกระบวนการของระบบที่ใช้ OpenGL ES API ให้อัปเดต EGL API

การเปลี่ยนแปลง Vulkan WSI สำหรับรูปแบบพิกเซลใหม่

อัปเดต Vulkan WSI ดังนี้

  1. เพิ่มเคสใหม่ให้กับฟังก์ชัน GetNativePixelFormat(VkFormat format) ใน swapchain.cpp

    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. เพิ่มรูปแบบใหม่ลงใน dEQP-VK ที่ external/deqp
  5. อัปเดตการทดสอบ Vulkan Conformance ใน vktApiExternalMemoryTests.cpp และ vktExternalMemoryUtil.cpp โดยการอนุมานการเปลี่ยนแปลงที่จำเป็นจากแหล่งที่มาที่มีอยู่ หรือติดต่อฝ่ายสนับสนุนของ Android ของเรา

การเปลี่ยนแปลง 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 enum ซึ่งแสดงดังต่อไปนี้ 
    static const GLenum androidFormats[] =
{
  ...
  GL_RGBA8,
  ...
};

ส่งการอัปเดต

ติดตาม สำหรับผู้ร่วมให้ข้อมูล เพื่อสร้างรายการการเปลี่ยนแปลงและแชร์กับทีมที่เหมาะสม