Clarify GPU API requirements for BufferUsage
Bug: 283989374
Test: n/a doc only change
Change-Id: I4caec722420d4fa2089d1f297f377408a1e674ae
diff --git a/graphics/common/aidl/android/hardware/graphics/common/BufferUsage.aidl b/graphics/common/aidl/android/hardware/graphics/common/BufferUsage.aidl
index 12bc441..0d1a094 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 @@
@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 @@
* 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,
}