diff --git a/include/system/graphics.h b/include/system/graphics.h index c3fca97bb..c9f595040 100644 --- a/include/system/graphics.h +++ b/include/system/graphics.h @@ -45,9 +45,12 @@ enum { /* * "linear" color pixel formats: * - * The pixel formats below contain sRGB data but are otherwise treated - * as linear formats, i.e.: no special operation is performed when - * reading or writing into a buffer in one of these formats + * When used with ANativeWindow, the dataSpace field describes the color + * space of the buffer. + * + * 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. */ HAL_PIXEL_FORMAT_RGBA_8888 = 1, HAL_PIXEL_FORMAT_RGBX_8888 = 2, @@ -55,28 +58,6 @@ enum { HAL_PIXEL_FORMAT_RGB_565 = 4, HAL_PIXEL_FORMAT_BGRA_8888 = 5, - /* - * sRGB color pixel formats: - * - * The red, green and blue components are stored in sRGB space, and converted - * to linear space when read, using the standard sRGB to linear equation: - * - * Clinear = Csrgb / 12.92 for Csrgb <= 0.04045 - * = (Csrgb + 0.055 / 1.055)^2.4 for Csrgb > 0.04045 - * - * When written the inverse transformation is performed: - * - * Csrgb = 12.92 * Clinear for Clinear <= 0.0031308 - * = 1.055 * Clinear^(1/2.4) - 0.055 for Clinear > 0.0031308 - * - * - * The alpha component, if present, is always stored in linear space and - * is left unmodified when read or written. - * - */ - HAL_PIXEL_FORMAT_sRGB_A_8888 = 0xC, - HAL_PIXEL_FORMAT_sRGB_X_8888 = 0xD, - /* * 0x100 - 0x1FF * @@ -111,6 +92,8 @@ enum { * cr_offset = y_size * cb_offset = y_size + c_size * + * When used with ANativeWindow, the dataSpace field describes the color + * space of the buffer. */ HAL_PIXEL_FORMAT_YV12 = 0x32315659, // YCrCb 4:2:0 Planar @@ -135,6 +118,8 @@ enum { * * size = stride * height * + * When used with ANativeWindow, the dataSpace field describes the color + * space of the buffer. */ HAL_PIXEL_FORMAT_Y8 = 0x20203859, @@ -159,6 +144,10 @@ enum { * * 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. */ HAL_PIXEL_FORMAT_Y16 = 0x20363159, @@ -167,7 +156,7 @@ enum { * * This format is exposed outside of the camera HAL to applications. * - * RAW_SENSOR is a single-channel, 16-bit, little endian format, typically + * RAW16 is a single-channel, 16-bit, little endian format, typically * representing raw Bayer-pattern images from an image sensor, with minimal * processing. * @@ -193,9 +182,12 @@ enum { * - GRALLOC_USAGE_HW_CAMERA_* * - GRALLOC_USAGE_SW_* * - GRALLOC_USAGE_RENDERSCRIPT + * + * When used with ANativeWindow, the dataSpace should be + * HAL_DATASPACE_ARBITRARY, as raw image sensor buffers require substantial + * extra metadata to define. */ HAL_PIXEL_FORMAT_RAW16 = 0x20, - HAL_PIXEL_FORMAT_RAW_SENSOR = 0x20, // TODO(rubenbrunk): Remove RAW_SENSOR. /* * Android RAW10 format: @@ -244,6 +236,10 @@ enum { * - 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. */ HAL_PIXEL_FORMAT_RAW10 = 0x25, @@ -261,6 +257,10 @@ enum { * - 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. */ HAL_PIXEL_FORMAT_RAW_OPAQUE = 0x24, @@ -276,6 +276,16 @@ enum { * * 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: + * + * dataSpace value | Buffer contents + * -------------------------------+----------------------------------------- + * HAL_DATASPACE_JFIF | An encoded JPEG image + * HAL_DATASPACE_DEPTH | An android_depth_points buffer + * Other | Unsupported + * */ HAL_PIXEL_FORMAT_BLOB = 0x21, @@ -292,6 +302,8 @@ enum { * 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). * + * When used with ANativeWindow, the dataSpace field describes the color + * space of the buffer. */ HAL_PIXEL_FORMAT_IMPLEMENTATION_DEFINED = 0x22, @@ -311,6 +323,9 @@ enum { * * This format is locked for use by gralloc's (*lock_ycbcr) method, and * locking with the (*lock) method will return an error. + * + * When used with ANativeWindow, the dataSpace field describes the color + * space of the buffer. */ HAL_PIXEL_FORMAT_YCbCr_420_888 = 0x23, @@ -354,6 +369,42 @@ struct android_ycbcr { uint32_t reserved[8]; }; +/** + * Structure used to define depth point clouds for format HAL_PIXEL_FORMAT_BLOB + * with dataSpace value of HAL_DATASPACE_DEPTH. + * When locking a native buffer of the above format and dataSpace value, + * the vaddr pointer can be cast to this structure. + * + * A variable-length list of (x,y,z) 3D points, as floats. + * + * @num_points is the number of points in the list + * + * @xyz_points is the flexible array of floating-point values. + * It contains (num_points) * 3 floats. + * + * For example: + * android_depth_points d = get_depth_buffer(); + * struct { + * float x; float y; float z; + * } firstPoint, lastPoint; + * + * firstPoint.x = d.xyz_points[0]; + * firstPoint.y = d.xyz_points[1]; + * firstPoint.z = d.xyz_points[2]; + * lastPoint.x = d.xyz_points[(d.num_points - 1) * 3 + 0]; + * lastPoint.y = d.xyz_points[(d.num_points - 1) * 3 + 1]; + * lastPoint.z = d.xyz_points[(d.num_points - 1) * 3 + 2]; + */ + +struct android_depth_points { + uint32_t num_points; + + /** reserved for future use, set to 0 by gralloc's (*lock)() */ + uint32_t reserved[8]; + + float xyz_points[]; +}; + /** * Transformation definitions * @@ -378,19 +429,33 @@ enum { }; /** - * Colorspace Definitions + * Dataspace Definitions * ====================== * - * Colorspace is the definition of how pixel values should be interpreted. - * It includes primaries (including white point) and the transfer - * characteristic function, which describes both gamma curve and numeric - * range (within the bit depth). + * Dataspace is the definition of how pixel values should be interpreted. + * + * For many formats, this is the colorspace of the image data, which includes + * primaries (including white point) and the transfer characteristic function, + * which describes both gamma curve and numeric range (within the bit depth). + * + * Other dataspaces include depth measurement data from a depth camera. */ -enum { +typedef enum android_dataspace { /* - * Arbitrary colorspace with manually defined characteristics. - * Colorspace definition must be communicated separately. + * 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. + */ + HAL_DATASPACE_UNKNOWN = 0x0, + + /* + * Arbitrary dataspace with manually defined characteristics. Definition + * for colorspaces or other meaning must be communicated separately. * * This is used when specifying primaries, transfer characteristics, * etc. separately. @@ -399,7 +464,57 @@ enum { * where a colorspace can have separately defined primaries, transfer * characteristics, etc. */ - HAL_COLORSPACE_ARBITRARY = 0x1, + HAL_DATASPACE_ARBITRARY = 0x1, + + /* + * RGB Colorspaces + * ----------------- + * + * Primaries are given using (x,y) coordinates in the CIE 1931 definition + * of x and y specified by ISO 11664-1. + * + * Transfer characteristics are the opto-electronic transfer characteristic + * at the source as a function of linear optical intensity (luminance). + */ + + /* + * sRGB linear encoding: + * + * The red, green, and blue components are stored in sRGB space, but + * are linear, not gamma-encoded. + * The RGB primaries and the white point are the same as BT.709. + * + * The values are encoded using the full range ([0,255] for 8-bit) for all + * components. + */ + HAL_DATASPACE_SRGB_LINEAR = 0x200, + + /* + * sRGB gamma encoding: + * + * The red, green and blue components are stored in sRGB space, and + * converted to linear space when read, using the standard sRGB to linear + * equation: + * + * Clinear = Csrgb / 12.92 for Csrgb <= 0.04045 + * = (Csrgb + 0.055 / 1.055)^2.4 for Csrgb > 0.04045 + * + * When written the inverse transformation is performed: + * + * Csrgb = 12.92 * Clinear for Clinear <= 0.0031308 + * = 1.055 * Clinear^(1/2.4) - 0.055 for Clinear > 0.0031308 + * + * + * The alpha component, if present, is always stored in linear space and + * is left unmodified when read or written. + * + * The RGB primaries and the white point are the same as BT.709. + * + * The values are encoded using the full range ([0,255] for 8-bit) for all + * components. + * + */ + HAL_DATASPACE_SRGB = 0x201, /* * YCbCr Colorspaces @@ -429,7 +544,7 @@ enum { * red 0.640 0.330 * white (D65) 0.3127 0.3290 */ - HAL_COLORSPACE_JFIF = 0x101, + HAL_DATASPACE_JFIF = 0x101, /* * ITU-R Recommendation 601 (BT.601) - 625-line @@ -456,7 +571,7 @@ enum { * red 0.640 0.330 * white (D65) 0.3127 0.3290 */ - HAL_COLORSPACE_BT601_625 = 0x102, + HAL_DATASPACE_BT601_625 = 0x102, /* * ITU-R Recommendation 601 (BT.601) - 525-line @@ -483,7 +598,7 @@ enum { * red 0.630 0.340 * white (D65) 0.3127 0.3290 */ - HAL_COLORSPACE_BT601_525 = 0x103, + HAL_DATASPACE_BT601_525 = 0x103, /* * ITU-R Recommendation 709 (BT.709) @@ -504,8 +619,20 @@ enum { * red 0.640 0.330 * white (D65) 0.3127 0.3290 */ - HAL_COLORSPACE_BT709 = 0x104, -}; + HAL_DATASPACE_BT709 = 0x104, + + /* + * The buffer contains depth ranging measurements from a depth camera. + * This value is valid with formats: + * HAL_PIXEL_FORMAT_Y16: 16-bit single channel depth image. + * HAL_PIXEL_FORMAT_BLOB: A depth point cloud, as + * a variable-length float (x,y,z) coordinate point list. + * The point cloud will be represented with the android_depth_points + * structure. + */ + HAL_DATASPACE_DEPTH = 0x1000 + +} android_dataspace_t; #ifdef __cplusplus } diff --git a/include/system/window.h b/include/system/window.h index bf93b79cc..af0418be8 100644 --- a/include/system/window.h +++ b/include/system/window.h @@ -262,6 +262,12 @@ enum { * the aspect ratio of the buffers produced. */ NATIVE_WINDOW_STICKY_TRANSFORM = 11, + + /** + * The default data space for the buffers as set by the consumer. + * The values are defined in graphics.h. + */ + NATIVE_WINDOW_DEFAULT_DATASPACE = 12 }; /* Valid operations for the (*perform)() hook. @@ -294,6 +300,7 @@ enum { NATIVE_WINDOW_SET_POST_TRANSFORM_CROP = 16, /* private */ NATIVE_WINDOW_SET_BUFFERS_STICKY_TRANSFORM = 17,/* private */ NATIVE_WINDOW_SET_SIDEBAND_STREAM = 18, + NATIVE_WINDOW_SET_BUFFERS_DATASPACE = 19 }; /* parameter for NATIVE_WINDOW_[API_][DIS]CONNECT */ @@ -498,6 +505,7 @@ struct ANativeWindow * NATIVE_WINDOW_SET_BUFFERS_GEOMETRY (deprecated) * NATIVE_WINDOW_SET_BUFFERS_TRANSFORM * NATIVE_WINDOW_SET_BUFFERS_TIMESTAMP + * NATIVE_WINDOW_SET_BUFFERS_DATASPACE * NATIVE_WINDOW_SET_BUFFERS_DIMENSIONS * NATIVE_WINDOW_SET_BUFFERS_FORMAT * NATIVE_WINDOW_SET_SCALING_MODE (private) @@ -798,6 +806,26 @@ static inline int native_window_set_buffers_format( return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_FORMAT, format); } +/* + * native_window_set_buffers_data_space(..., int dataSpace) + * All buffers queued after this call will be associated with the dataSpace + * parameter specified. + * + * dataSpace specifies additional information about the buffer that's dependent + * on the buffer format and the endpoints. For example, it can be used to convey + * the color space of the image data in the buffer, or it can be used to + * indicate that the buffers contain depth measurement data instead of color + * images. The default dataSpace is 0, HAL_DATASPACE_UNKNOWN, unless it has been + * overridden by the consumer. + */ +static inline int native_window_set_buffers_data_space( + struct ANativeWindow* window, + android_dataspace_t dataSpace) +{ + return window->perform(window, NATIVE_WINDOW_SET_BUFFERS_DATASPACE, + dataSpace); +} + /* * native_window_set_buffers_transform(..., int transform) * All buffers queued after this call will be displayed transformed according