graphics: clean up PixelFormat docs (19e3d979) · Commits · e / os / android_hardware_interfaces

current.txt

+1 −1

Original line number	Diff line number	Diff line
		@@ -98,7 +98,7 @@ bd366b83d8d565d0e8bfabff3adfcab0259d75b4e2a9f8e1b91e11d1593a2ffb android.hardwar
		17971eb8a482893dadcfc16e0583f492d42a034ef95d9b0b709417af30838396 android.hardware.graphics.allocator@2.0::IAllocator
		60bf42a4898e4fb70dbd720b263aeafd7f35f5e1a5effeabb4d5d659878a5f18 android.hardware.graphics.bufferqueue@1.0::IGraphicBufferProducer
		b8a75617b9ec12bea641f3a73d4025a33e8b9a2f9169dd46094af56adf9249c5 android.hardware.graphics.bufferqueue@1.0::IProducerListener
		3e7aa6cbfca575299bc511f618373576def6e07c5bf082d2b2f638be0d0d347c android.hardware.graphics.common@1.0::types
		78f973cf47a45d9d842c95888324dfc44e24a6fa3e5a1d0f726dfe37a863b634 android.hardware.graphics.common@1.0::types
		b3aac6c3817f039964fcd62268274b3039e17bd7d0d5b40b4d1d1c7b19a1f866 android.hardware.graphics.composer@2.1::IComposer
		b19d00eb8a8b3b0034a0321f22e8f32162bf4c2aebbce6da22c025f56e459ea2 android.hardware.graphics.composer@2.1::IComposerCallback
		e992684e690dfe67a8cbeab5005bfa3fa9c2bf3d4b0b75657fb1f0c2d5dd2bae android.hardware.graphics.composer@2.1::IComposerClient

graphics/common/1.0/types.hal

+183 −202

Original line number	Diff line number	Diff line
		@@ -17,44 +17,77 @@
		package android.hardware.graphics.common@1.0;

		/**
		* pixel format definitions
		* Common enumeration and structure definitions for all graphics HALs.
		*/

		/**
		* Pixel formats for graphics buffers.
		*/
		@export(name="android_pixel_format_t", value_prefix="HAL_PIXEL_FORMAT_")
		enum PixelFormat : int32_t {
		/**
		* "linear" color pixel formats:
		* 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,

		/**
		* 32-bit format that has 8-bit R, G, B, and unused 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.
		*/
		RGBX_8888 = 0x2,

		/**
		* 24-bit format that has 8-bit R, G, and B components, in that order,
		* from the lowest memory address to the highest memory address.
		*
		* When used with ANativeWindow, the dataSpace field describes the color
		* space of the buffer.
		* The component values are unsigned normalized to the range [0, 1], whose
		* interpretation is defined by the dataspace.
		*/
		RGB_888 = 0x3,

		/**
		* 16-bit packed format that has 5-bit R, 6-bit G, and 5-bit B components,
		* in that order, from the most-sigfinicant bits to the least-significant
		* bits.
		*
		* The color space determines, for example, if the formats are linear or
		* gamma-corrected; or whether any special operations are performed when
		* reading or writing into a buffer in one of these formats.
		* The component values are unsigned normalized to the range [0, 1], whose
		* interpretation is defined by the dataspace.
		*/
		RGBA_8888 = 1,
		RGBX_8888 = 2,
		RGB_888 = 3,
		RGB_565 = 4,
		BGRA_8888 = 5,
		RGB_565 = 0x4,

		/** Legacy formats (deprecated), used by ImageFormat.java */
		/**
		* 32-bit format that has 8-bit B, G, R, 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.
		*/
		BGRA_8888 = 0x5,

		/**
		* Legacy formats deprecated in favor of YCBCR_420_888.
		*/
		YCBCR_422_SP = 0x10, // NV16
		YCRCB_420_SP = 0x11, // NV21
		YCBCR_422_I = 0x14, // YUY2

		/**
		* The following formats use a 16bit float per color component.
		* 64-bit format that has 16-bit R, G, B, and A components, in that order,
		* from the lowest memory address to the highest memory address.
		*
		* When used with ANativeWindow, the dataSpace field describes the color
		* space of the buffer.
		* The component values are signed floats, whose interpretation is defined
		* by the dataspace.
		*/
		RGBA_FP16 = 0x16,

		/**
		* Android RAW sensor format:
		*
		* This format is exposed outside of the camera HAL to applications.
		*
		* RAW16 is a single-channel, 16-bit, little endian format, typically
		* representing raw Bayer-pattern images from an image sensor, with minimal
		* processing.
		@@ -76,20 +109,21 @@ enum PixelFormat : int32_t {
		*
		* size = stride * height * 2
		*
		* This format must be accepted by the gralloc module when used with the
		* This format must be accepted by the allocator when used with the
		* following usage flags:
		* - GRALLOC_USAGE_HW_CAMERA_*
		* - GRALLOC_USAGE_SW_*
		* - GRALLOC_USAGE_RENDERSCRIPT
		*
		* When used with ANativeWindow, the mapping of the dataSpace field to
		* buffer contents for RAW16 is as follows:
		* - BufferUsage::CAMERA_*
		* - BufferUsage::CPU_*
		* - BufferUsage::RENDERSCRIPT
		*
		* dataSpace value \| Buffer contents
		* The mapping of the dataspace to buffer contents for RAW16 is as
		* follows:
		*
		* Dataspace value \| Buffer contents
		* -------------------------------+-----------------------------------------
		* HAL_DATASPACE_ARBITRARY \| Raw image sensor data, layout is as
		* Dataspace::ARBITRARY \| Raw image sensor data, layout is as
		* \| defined above.
		* HAL_DATASPACE_DEPTH \| Unprocessed implementation-dependent raw
		* Dataspace::DEPTH \| Unprocessed implementation-dependent raw
		* \| depth measurements, opaque with 16 bit
		* \| samples.
		* Other \| Unsupported
		@@ -97,10 +131,8 @@ enum PixelFormat : int32_t {
		RAW16 = 0x20,

		/**
		* Android binary blob graphics buffer format:
		*
		* This format is used to carry task-specific data which does not have a
		* standard image structure. The details of the format are left to the two
		* BLOB is used to carry task-specific data which does not have a standard
		* image structure. The details of the format are left to the two
		* endpoints.
		*
		* A typical use case is for transporting JPEG-compressed images from the
		@@ -109,85 +141,74 @@ enum PixelFormat : int32_t {
		* Buffers of this format must have a height of 1, and width equal to their
		* size in bytes.
		*
		* When used with ANativeWindow, the mapping of the dataSpace field to
		* buffer contents for BLOB is as follows:
		* The mapping of the dataspace to buffer contents for BLOB is as
		* follows:
		*
		* dataSpace value \| Buffer contents
		* Dataspace value \| Buffer contents
		* -------------------------------+-----------------------------------------
		* HAL_DATASPACE_JFIF \| An encoded JPEG image
		* HAL_DATASPACE_DEPTH \| An android_depth_points buffer
		* HAL_DATASPACE_SENSOR \| Sensor event data.
		* Dataspace::JFIF \| An encoded JPEG image
		* Dataspace::DEPTH \| An android_depth_points buffer
		* Dataspace::SENSOR \| Sensor event data.
		* Other \| Unsupported
		*
		*/
		BLOB = 0x21,

		/**
		* Android format indicating that the choice of format is entirely up to the
		* device-specific Gralloc implementation.
		* A format indicating that the choice of format is entirely up to the
		* allocator.
		*
		* The Gralloc implementation should examine the usage bits passed in when
		* allocating a buffer with this format, and it should derive the pixel
		* format from those usage flags. This format will never be used with any
		* of the GRALLOC_USAGE_SW_* usage flags.
		* The allocator should examine the usage bits passed in when allocating a
		* buffer with this format, and it should derive the pixel format from
		* those usage flags. This format must never be used with any of the
		* BufferUsage::CPU_* usage flags.
		*
		* If a buffer of this format is to be used as an OpenGL ES texture, the
		* framework will assume that sampling the texture will always return an
		* alpha value of 1.0 (i.e. the buffer contains only opaque pixel values).
		* Even when the internally chosen format has an alpha component, the
		* clients must assume the alpha vlaue to be 1.0.
		*
		* When used with ANativeWindow, the dataSpace field describes the color
		* space of the buffer.
		* The interpretation of the component values is defined by the dataspace.
		*/
		IMPLEMENTATION_DEFINED = 0x22,

		/**
		* Android flexible YCbCr 4:2:0 formats
		*
		* This format allows platforms to use an efficient YCbCr/YCrCb 4:2:0
		* buffer layout, while still describing the general format in a
		* layout-independent manner. While called YCbCr, it can be
		* used to describe formats with either chromatic ordering, as well as
		* layout-independent manner. While called YCbCr, it can be used to
		* describe formats with either chromatic ordering, as well as
		* whole planar or semiplanar layouts.
		*
		* struct android_ycbcr (below) is the the struct used to describe it.
		*
		* This format must be accepted by the gralloc module when
		* USAGE_SW_WRITE_* or USAGE_SW_READ_* are set.
		* This format must be accepted by the allocator when BufferUsage::CPU_*
		* are set.
		*
		* This format is locked for use by gralloc's (*lock_ycbcr) method, and
		* locking with the (*lock) method will return an error.
		* Buffers with this format must be locked with IMapper::lockYCbCr.
		* Locking with IMapper::lock must return an error.
		*
		* When used with ANativeWindow, the dataSpace field describes the color
		* space of the buffer.
		* The interpretation of the component values is defined by the dataspace.
		*/
		YCBCR_420_888 = 0x23,

		/**
		* Android opaque RAW format:
		*
		* This format is exposed outside of the camera HAL to applications.
		*
		* RAW_OPAQUE is a format for unprocessed raw image buffers coming from an
		* image sensor. The actual structure of buffers of this format is
		* implementation-dependent.
		*
		* This format must be accepted by the gralloc module when used with the
		* This format must be accepted by the allocator when used with the
		* following usage flags:
		* - GRALLOC_USAGE_HW_CAMERA_*
		* - GRALLOC_USAGE_SW_*
		* - GRALLOC_USAGE_RENDERSCRIPT
		*
		* When used with ANativeWindow, the dataSpace field should be
		* HAL_DATASPACE_ARBITRARY, as raw image sensor buffers require substantial
		* extra metadata to define.
		* - BufferUsage::CAMERA_*
		* - BufferUsage::CPU_*
		* - BufferUsage::RENDERSCRIPT
		*
		* The mapping of the dataspace to buffer contents for RAW_OPAQUE is as
		* follows:
		*
		* Dataspace value \| Buffer contents
		* -------------------------------+-----------------------------------------
		* Dataspace::ARBITRARY \| Raw image sensor data.
		* Other \| Unsupported
		*/
		RAW_OPAQUE = 0x24,

		/**
		* Android RAW10 format:
		*
		* This format is exposed outside of the camera HAL to applications.
		*
		* RAW10 is a single-channel, 10-bit per pixel, densely packed in each row,
		* unprocessed format, usually representing raw Bayer-pattern images coming from
		* an image sensor.
		@@ -225,23 +246,24 @@ enum PixelFormat : int32_t {
		* larger than width * (10 / 8), padding bytes will be present at the end of each
		* row (including the last row).
		*
		* This format must be accepted by the gralloc module when used with the
		* This format must be accepted by the allocator when used with the
		* following usage flags:
		* - GRALLOC_USAGE_HW_CAMERA_*
		* - GRALLOC_USAGE_SW_*
		* - GRALLOC_USAGE_RENDERSCRIPT
		*
		* When used with ANativeWindow, the dataSpace field should be
		* HAL_DATASPACE_ARBITRARY, as raw image sensor buffers require substantial
		* extra metadata to define.
		* - BufferUsage::CAMERA_*
		* - BufferUsage::CPU_*
		* - BufferUsage::RENDERSCRIPT
		*
		* The mapping of the dataspace to buffer contents for RAW10 is as
		* follows:
		*
		* Dataspace value \| Buffer contents
		* -------------------------------+-----------------------------------------
		* Dataspace::ARBITRARY \| Raw image sensor data.
		* Other \| Unsupported
		*/
		RAW10 = 0x25,

		/**
		* Android RAW12 format:
		*
		* This format is exposed outside of camera HAL to applications.
		*
		* RAW12 is a single-channel, 12-bit per pixel, densely packed in each row,
		* unprocessed format, usually representing raw Bayer-pattern images coming from
		* an image sensor.
		@@ -275,108 +297,58 @@ enum PixelFormat : int32_t {
		* larger than width * (12 / 8), padding bytes will be present at the end of
		* each row (including the last row).
		*
		* This format must be accepted by the gralloc module when used with the
		* This format must be accepted by the allocator when used with the
		* following usage flags:
		* - GRALLOC_USAGE_HW_CAMERA_*
		* - GRALLOC_USAGE_SW_*
		* - GRALLOC_USAGE_RENDERSCRIPT
		*
		* When used with ANativeWindow, the dataSpace field should be
		* HAL_DATASPACE_ARBITRARY, as raw image sensor buffers require substantial
		* extra metadata to define.
		*/
		RAW12 = 0x26,

		/**
		* Android flexible YCbCr 4:2:2 formats
		* - BufferUsage::CAMERA_*
		* - BufferUsage::CPU_*
		* - BufferUsage::RENDERSCRIPT
		*
		* This format allows platforms to use an efficient YCbCr/YCrCb 4:2:2
		* buffer layout, while still describing the general format in a
		* layout-independent manner. While called YCbCr, it can be
		* used to describe formats with either chromatic ordering, as well as
		* whole planar or semiplanar layouts.
		* The mapping of the dataspace to buffer contents for RAW12 is as
		* follows:
		*
		* This format is currently only used by SW readable buffers
		* produced by MediaCodecs, so the gralloc module can ignore this format.
		* Dataspace value \| Buffer contents
		* -------------------------------+-----------------------------------------
		* Dataspace::ARBITRARY \| Raw image sensor data.
		* Other \| Unsupported
		*/
		YCBCR_422_888 = 0x27,
		RAW12 = 0x26,

		/**
		* Android flexible YCbCr 4:4:4 formats
		*
		* This format allows platforms to use an efficient YCbCr/YCrCb 4:4:4
		* buffer layout, while still describing the general format in a
		* layout-independent manner. While called YCbCr, it can be
		* used to describe formats with either chromatic ordering, as well as
		* whole planar or semiplanar layouts.
		*
		* This format is currently only used by SW readable buffers
		* produced by MediaCodecs, so the gralloc module can ignore this format.
		* Must not use.
		*/
		YCBCR_422_888 = 0x27,
		YCBCR_444_888 = 0x28,

		/**
		* Android flexible RGB 888 formats
		*
		* This format allows platforms to use an efficient RGB/BGR/RGBX/BGRX
		* buffer layout, while still describing the general format in a
		* layout-independent manner. While called RGB, it can be
		* used to describe formats with either color ordering and optional
		* padding, as well as whole planar layout.
		*
		* This format is currently only used by SW readable buffers
		* produced by MediaCodecs, so the gralloc module can ignore this format.
		*/
		FLEX_RGB_888 = 0x29,

		/**
		* Android flexible RGBA 8888 formats
		*
		* This format allows platforms to use an efficient RGBA/BGRA/ARGB/ABGR
		* buffer layout, while still describing the general format in a
		* layout-independent manner. While called RGBA, it can be
		* used to describe formats with any of the component orderings, as
		* well as whole planar layout.
		*
		* This format is currently only used by SW readable buffers
		* produced by MediaCodecs, so the gralloc module can ignore this format.
		*/
		FLEX_RGBA_8888 = 0x2A,

		/**
		* The following formats use 10bit integers for R, G, and B and
		* 2 bits for alpha. This is used to improve color precision on
		* wide-color devices, e.g. Display-P3 or scRGB.
		* 32-bit packed format that has 2-bit A, 10-bit B, G, and R components,
		* in that order, from the most-sigfinicant bits to the least-significant
		* bits.
		*
		* When used with ANativeWindow, the dataSpace field describes the color
		* space of the buffer.
		* The component values are unsigned normalized to the range [0, 1], whose
		* interpretation is defined by the dataspace.
		*/
		RGBA_1010102 = 0x2B,

		/**
		* Must not use. 0x100 is reserved for vendor extensions.
		*/
		JPEG = 0x100,

		/**
		* 0x101 - 0x1FF
		* 0x100 - 0x1FF
		*
		* This range is reserved for pixel formats that are specific to the HAL
		* implementation. Implementations can use any value in this range to
		* communicate video pixel formats between their HAL modules. These formats
		* must not have an alpha channel. Additionally, an EGLimage created from a
		* gralloc buffer of one of these formats must be supported for use with the
		* GL_OES_EGL_image_external OpenGL ES extension.
		* This range is reserved for vendor extensions. Formats in this range
		* must support BufferUsage::GPU_TEXTURE. Clients must assume they do not
		* have an alpha component.
		*/

		/**
		* Android Y8 format:
		*
		* This format is exposed outside of the HAL to the framework.
		* The expected gralloc usage flags are SW_* and HW_CAMERA_*,
		* and no other HW_ flags will be used.
		*
		* Y8 is a YUV planar format comprised of a WxH Y plane,
		* with each pixel being represented by 8 bits.
		*
		* It is equivalent to just the Y plane from YV12.
		* Y8 is a YUV planar format comprised of a WxH Y plane, with each pixel
		* being represented by 8 bits. It is equivalent to just the Y plane from
		* YV12.
		*
		* This format assumes
		* - an even width
		@@ -386,22 +358,21 @@ enum PixelFormat : int32_t {
		*
		* size = stride * height
		*
		* When used with ANativeWindow, the dataSpace field describes the color
		* space of the buffer.
		* This format must be accepted by the allocator when used with the
		* following usage flags:
		*
		* - BufferUsage::CAMERA_*
		* - BufferUsage::CPU_*
		*
		* The component values are unsigned normalized to the range [0, 1], whose
		* interpretation is defined by the dataspace.
		*/
		Y8 = 0x20203859,

		/**
		* Android Y16 format:
		*
		* This format is exposed outside of the HAL to the framework.
		* The expected gralloc usage flags are SW_* and HW_CAMERA_*,
		* and no other HW_ flags will be used.
		*
		* Y16 is a YUV planar format comprised of a WxH Y plane,
		* with each pixel being represented by 16 bits.
		*
		* It is just like Y8, but has double the bits per pixel (little endian).
		* Y16 is a YUV planar format comprised of a WxH Y plane, with each pixel
		* being represented by 16 bits. It is just like Y8, but has double the
		* bits per pixel (little endian).
		*
		* This format assumes
		* - an even width
		@@ -412,21 +383,20 @@ enum PixelFormat : int32_t {
		*
		* size = stride * height * 2
		*
		* When used with ANativeWindow, the dataSpace field describes the color
		* space of the buffer, except that dataSpace field
		* HAL_DATASPACE_DEPTH indicates that this buffer contains a depth
		* image where each sample is a distance value measured by a depth camera,
		* plus an associated confidence value.
		* This format must be accepted by the allocator when used with the
		* following usage flags:
		*
		* - BufferUsage::CAMERA_*
		* - BufferUsage::CPU_*
		*
		* The component values are unsigned normalized to the range [0, 1], whose
		* interpretation is defined by the dataspace. When the dataspace is
		* Dataspace::DEPTH, each pixel is a distance value measured by a depth
		* camera, plus an associated confidence value.
		*/
		Y16 = 0x20363159,

		/**
		* Android YUV format:
		*
		* This format is exposed outside of the HAL to software decoders and
		* applications. EGLImageKHR must support it in conjunction with the
		* OES_EGL_image_external extension.
		*
		* YV12 is a 4:2:0 YCrCb planar format comprised of a WxH Y plane followed
		* by (W/2) x (H/2) Cr and Cb planes.
		*
		@@ -443,8 +413,19 @@ enum PixelFormat : int32_t {
		* cr_offset = y_size
		* cb_offset = y_size + c_size
		*
		* When used with ANativeWindow, the dataSpace field describes the color
		* space of the buffer.
		* This range is reserved for vendor extensions. Formats in this range
		* must support BufferUsage::GPU_TEXTURE. Clients must assume they do not
		* have an alpha component.
		*
		* This format must be accepted by the allocator when used with the
		* following usage flags:
		*
		* - BufferUsage::CAMERA_*
		* - BufferUsage::CPU_*
		* - BufferUsage::GPU_TEXTURE
		*
		* The component values are unsigned normalized to the range [0, 1], whose
		* interpretation is defined by the dataspace.
		*/
		YV12 = 0x32315659, // YCrCb 4:2:0 Planar
		};