From e5c4f5546ae88683fe11924621a338111476a150 Mon Sep 17 00:00:00 2001 From: Alec Mouri Date: Fri, 23 Jun 2023 19:49:05 +0000 Subject: [PATCH] Adjust documentation for UNKNOWN dataspaces. Summarize the recommendations in {STANDARD, TRANSFER, RANGE}_UNSPECIFIED, but also indicate the UNKNOWN isn't really appropriate to signal. Bug: 288461753 Change-Id: I237e45b7d83ed620ee79b9e39aed73fe71a047b0 Test: docs --- .../hardware/graphics/common/Dataspace.aidl | 25 +++++++++++++++---- 1 file changed, 20 insertions(+), 5 deletions(-) diff --git a/graphics/common/aidl/android/hardware/graphics/common/Dataspace.aidl b/graphics/common/aidl/android/hardware/graphics/common/Dataspace.aidl index 3ff0a6534b..4b6613e914 100644 --- a/graphics/common/aidl/android/hardware/graphics/common/Dataspace.aidl +++ b/graphics/common/aidl/android/hardware/graphics/common/Dataspace.aidl @@ -23,11 +23,26 @@ enum Dataspace { /** * Default-assumption data space, when not explicitly specified. * - * It is safest to assume the buffer is an image with sRGB primaries and - * encoding ranges, but the consumer and/or the producer of the data may - * simply be using defaults. No automatic gamma transform should be - * expected, except for a possible display gamma transform when drawn to a - * screen. + * IAllocator implementations must not assume a particular dataspace interpretation when + * allocating a buffer. That is, the dataspace stored on a buffer's metadata must + * explicitly be UNKNOWN at the time of allocation. All other vendor implementations (for + * example, IComposer) are suggested to assume that the buffer is an image that conforms + * to the recommendations outlined by STANDARD_UNSPECIFIED, TRANSFER_UNSPECIFIED, and + * RANGE_UNSPECIFIED in order to avoid obviously-broken behavior. + * + * This means: + * - RGB buffers may be assumed to follow sRGB (IEC 61966-2.1) + * - YCbCr buffers smaller than 720p may be assumed to follow BT. 601-7 + * - YCbCr buffers at least 720p may be assumed to follow BT. 709-6 + * - Y buffers are full range with an undefined transfer and primaries + * - All other buffer formats may be treated in an implementation-defined manner + * + * It is the framework's - and application's - responsibility to communicate + * an accurate dataspace for any buffers throughout the system to guarantee + * well-defined behavior. For the framework, this means translating UNKNOWN + * dataspaces to a chosen default, and setting gralloc metadata on the buffer + * accordingly. For the application, this means signaling a defined dataspace + * to any framework apis. */ UNKNOWN = 0x0,