From 9db00ec784950ad50aefa794d370670dafef62f1 Mon Sep 17 00:00:00 2001 From: John Reck Date: Thu, 31 Aug 2023 17:41:18 -0400 Subject: [PATCH] Clarify GPU API requirements for BufferUsage Bug: 283989374 Test: n/a doc only change Change-Id: I4caec722420d4fa2089d1f297f377408a1e674ae --- .../hardware/graphics/common/BufferUsage.aidl | 124 ++++++++++-------- 1 file changed, 68 insertions(+), 56 deletions(-) diff --git a/graphics/common/aidl/android/hardware/graphics/common/BufferUsage.aidl b/graphics/common/aidl/android/hardware/graphics/common/BufferUsage.aidl index 12bc441b72..0d1a094b36 100644 --- a/graphics/common/aidl/android/hardware/graphics/common/BufferUsage.aidl +++ b/graphics/common/aidl/android/hardware/graphics/common/BufferUsage.aidl @@ -24,35 +24,47 @@ package android.hardware.graphics.common; @Backing(type="long") enum BufferUsage { /** bit 0-3 is an enum */ - CPU_READ_MASK = 0xf, + CPU_READ_MASK = 0xf, /** buffer is never read by CPU */ - CPU_READ_NEVER = 0, + CPU_READ_NEVER = 0, /** buffer is rarely read by CPU */ - CPU_READ_RARELY = 2, + CPU_READ_RARELY = 2, /** buffer is often read by CPU */ - CPU_READ_OFTEN = 3, + CPU_READ_OFTEN = 3, /** bit 4-7 is an enum */ - CPU_WRITE_MASK = 0xf << 4, + CPU_WRITE_MASK = 0xf << 4, /** buffer is never written by CPU */ - CPU_WRITE_NEVER = 0 << 4, + CPU_WRITE_NEVER = 0 << 4, /** buffer is rarely written by CPU */ - CPU_WRITE_RARELY = 2 << 4, + CPU_WRITE_RARELY = 2 << 4, /** buffer is often written by CPU */ - CPU_WRITE_OFTEN = 3 << 4, + CPU_WRITE_OFTEN = 3 << 4, - /** buffer is used as a GPU texture */ - GPU_TEXTURE = 1 << 8, + /** + * Buffer may be used as a GPU texture + * + * Buffers allocated with this flag must be + * texturable both in EGL/GL & Vulkan via + * their respective external memory extensions + */ + GPU_TEXTURE = 1 << 8, - /** buffer is used as a GPU render target */ - GPU_RENDER_TARGET = 1 << 9, + /** + * Buffer may be used as a GPU render target + * + * Buffers allocated with this flag must be + * renderable both in EGL/GL & Vulkan via + * their respective external memory extensions + */ + GPU_RENDER_TARGET = 1 << 9, /** bit 10 must be zero */ /** buffer is used as a composer HAL overlay layer */ - COMPOSER_OVERLAY = 1 << 11, + COMPOSER_OVERLAY = 1 << 11, /** buffer is used as a composer HAL client target */ - COMPOSER_CLIENT_TARGET = 1 << 12, + COMPOSER_CLIENT_TARGET = 1 << 12, /** bit 13 must be zero */ @@ -61,86 +73,86 @@ enum BufferUsage { * contents (or information derived from the contents) into unprotected * memory. */ - PROTECTED = 1 << 14, + PROTECTED = 1 << 14, /** buffer is used as a hwcomposer HAL cursor layer */ - COMPOSER_CURSOR = 1 << 15, + COMPOSER_CURSOR = 1 << 15, /** buffer is used as a video encoder input */ - VIDEO_ENCODER = 1 << 16, + VIDEO_ENCODER = 1 << 16, /** buffer is used as a camera HAL output */ - CAMERA_OUTPUT = 1 << 17, + CAMERA_OUTPUT = 1 << 17, /** buffer is used as a camera HAL input */ - CAMERA_INPUT = 1 << 18, + CAMERA_INPUT = 1 << 18, /** bit 19 must be zero */ /** buffer is used as a renderscript allocation */ - RENDERSCRIPT = 1 << 20, + RENDERSCRIPT = 1 << 20, /** bit 21 must be zero */ /** buffer is used as a video decoder output */ - VIDEO_DECODER = 1 << 22, + VIDEO_DECODER = 1 << 22, /** buffer is used as a sensor direct report output */ - SENSOR_DIRECT_DATA = 1 << 23, + SENSOR_DIRECT_DATA = 1 << 23, /** * buffer is used as as an OpenGL shader storage or uniform * buffer object */ - GPU_DATA_BUFFER = 1 << 24, + GPU_DATA_BUFFER = 1 << 24, /** buffer is used as a cube map texture */ - GPU_CUBE_MAP = 1 << 25, + GPU_CUBE_MAP = 1 << 25, /** buffer contains a complete mipmap hierarchy */ - GPU_MIPMAP_COMPLETE = 1 << 26, + GPU_MIPMAP_COMPLETE = 1 << 26, /** * Buffer is used as input for HEIC encoder. */ - HW_IMAGE_ENCODER = 1 << 27, + HW_IMAGE_ENCODER = 1 << 27, /* Bits 28-31 are reserved for vendor usage */ /** - * Buffer is used for front-buffer rendering. - * - * To satisfy an allocation with this usage, the resulting buffer - * must operate as equivalent to shared memory for all targets. - * - * For CPU_USAGE_* other than NEVER, this means the buffer must - * "lock in place". The buffers must be directly accessible via mapping. - * - * For GPU_RENDER_TARGET the buffer must behave equivalent to a - * single-buffered EGL surface. For example glFlush must perform - * a flush, same as if the default framebuffer was single-buffered. - * - * For COMPOSER_* the HWC must not perform any caching for this buffer - * when submitted for composition. HWCs do not need to do any form - * of auto-refresh, and they are allowed to cache composition results between - * presents from SF (such as for panel self-refresh), but for any given - * present the buffer must be composited from even if it otherwise appears - * to be the same as a previous composition. - * - * If the GPU & HWC supports EGL_SINGLE_BUFFER, then it is recommended that - * FRONT_BUFFER usage is supported for the same formats as supported by - * EGL_SINGLE_BUFFER. In particular, it is recommended that the following - * combination is supported when possible: - * Format = RGBA_8888 - * Usage = FRONT_BUFFER | GPU_RENDER_TARGET | COMPOSER_OVERLAY - * - */ - FRONT_BUFFER = 1L << 32, + * Buffer is used for front-buffer rendering. + * + * To satisfy an allocation with this usage, the resulting buffer + * must operate as equivalent to shared memory for all targets. + * + * For CPU_USAGE_* other than NEVER, this means the buffer must + * "lock in place". The buffers must be directly accessible via mapping. + * + * For GPU_RENDER_TARGET the buffer must behave equivalent to a + * single-buffered EGL surface. For example glFlush must perform + * a flush, same as if the default framebuffer was single-buffered. + * + * For COMPOSER_* the HWC must not perform any caching for this buffer + * when submitted for composition. HWCs do not need to do any form + * of auto-refresh, and they are allowed to cache composition results between + * presents from SF (such as for panel self-refresh), but for any given + * present the buffer must be composited from even if it otherwise appears + * to be the same as a previous composition. + * + * If the GPU & HWC supports EGL_SINGLE_BUFFER, then it is recommended that + * FRONT_BUFFER usage is supported for the same formats as supported by + * EGL_SINGLE_BUFFER. In particular, it is recommended that the following + * combination is supported when possible: + * Format = RGBA_8888 + * Usage = FRONT_BUFFER | GPU_RENDER_TARGET | COMPOSER_OVERLAY + * + */ + FRONT_BUFFER = 1L << 32, /** bits 28-31 are reserved for vendor extensions */ - VENDOR_MASK = 0xf << 28, + VENDOR_MASK = 0xf << 28, /** bits 33-47 must be zero and are reserved for future versions */ /** bits 48-63 are reserved for vendor extensions */ - VENDOR_MASK_HI = (1L * 0xffff) << 48, + VENDOR_MASK_HI = (1L * 0xffff) << 48, }