From 57d570d4e893d676e64c2d8b107671f454f9bed2 Mon Sep 17 00:00:00 2001 From: Igor Murashkin Date: Thu, 6 Feb 2014 15:35:37 -0800 Subject: [PATCH] camera_metadata: Add tags for querying capabilities of a camera device Change-Id: I955b514f9fe66205d241cd4072aa6ddf71efb53c --- camera/docs/docs.html | 457 ++++++++++++++++++++++++++- camera/docs/metadata_properties.xml | 287 ++++++++++++++++- camera/include/system/camera_metadata_tags.h | 14 + camera/src/camera_metadata_tag_info.c | 48 +++ 4 files changed, 795 insertions(+), 11 deletions(-) diff --git a/camera/docs/docs.html b/camera/docs/docs.html index 2e0afee1..74aa052a 100644 --- a/camera/docs/docs.html +++ b/camera/docs/docs.html @@ -427,6 +427,10 @@
  • android.request.maxNumInputStreams
  • android.request.pipelineMaxDepth
  • android.request.partialResultCount
    • +
  • android.request.availableCapabilities
    • +
  • android.request.availableRequestKeys
    • +
  • android.request.availableResultKeys
    • +
  • android.request.availableCharacteristicsKeys
  • @@ -9529,6 +9533,415 @@ the metadata via later partial results.

    + + + + android.request.availableCapabilities + + + byte + + [public] + + + + + + +

    List of capabilities that the camera device +advertises as fully supporting.

    + + + + + + + + + + + + + + Details + + + +

    A capability is a contract that the camera device makes in order +to be able to satisfy one or more use cases.

    +

    Listing a capability guarantees that the whole set of features +required to support a common use will all be available.

    +

    Using a subset of the functionality provided by an unsupported +capability may be possible on a specific camera device implementation; +to do this query each of android.request.availableRequestKeys, +android.request.availableResultKeys, +android.request.availableCharacteristicsKeys.

    +

    XX: Maybe these should go into android.info.supportedHardwareLevel +as a table instead?

    +

    The following capabilities are guaranteed to be available on +android.info.supportedHardwareLevel == FULL devices:

    + +

    Other capabilities may be available on either FULL or LIMITED +devices, but the app. should query this field to be sure.

    + + + + + HAL Implementation Details + + + +

    Additional constraint details per-capability will be available +in the Compatibility Test Suite.

    +

    BACKWARD_COMPATIBLE capability requirements are not explicitly listed. +Instead refer to "BC" tags and the camera CTS tests in the +android.hardware.cts package.

    +

    Listed controls that can be either request or result (e.g. +android.sensor.exposureTime) must be available both in the +request and the result in order to be considered to be +capability-compliant.

    +

    For example, if the HAL claims to support MANUAL control, +then exposure time must be configurable via the request and +the actual exposure applied must be available via +the result.

    + + + + + + + + + + android.request.availableRequestKeys + + + int32 + x + + + n + + [hidden] + + + + + +

    A list of all keys that the camera device has available +to use with CaptureRequest.

    + + + + + + + + + + + + + + Details + + + +

    Attempting to set a key into a CaptureRequest that is not +listed here will result in an invalid request and will be rejected +by the camera device.

    +

    This field can be used to query the feature set of a camera device +at a more granular level than capabilities. This is especially +important for optional keys that are not listed under any capability +in android.request.availableCapabilities.

    +

    TODO: This should be used by #getAvailableCaptureRequestKeys.

    + + + + + HAL Implementation Details + + + +

    Vendor tags must not be listed here. Use the vendor tag metadata +extensions C api instead (refer to camera3.h for more details).

    +

    Setting/getting vendor tags will be checked against the metadata +vendor extensions API and not against this field.

    +

    The HAL must not consume any request tags that are not listed either +here or in the vendor tag list.

    +

    The public camera2 API will always make the vendor tags visible +via CameraCharacteristics#getAvailableCaptureRequestKeys.

    + + + + + + + + + + android.request.availableResultKeys + + + int32 + x + + + n + + [hidden] + + + + + +

    A list of all keys that the camera device has available +to use with CaptureResult.

    + + + + + + + + + + + + + + Details + + + +

    Attempting to get a key from a CaptureResult that is not +listed here will always return a null value. Getting a key from +a CaptureResult that is listed here must never return a null +value.

    +

    The following keys may return null unless they are enabled:

    + +

    (Those sometimes-null keys should nevertheless be listed here +if they are available.)

    +

    This field can be used to query the feature set of a camera device +at a more granular level than capabilities. This is especially +important for optional keys that are not listed under any capability +in android.request.availableCapabilities.

    +

    TODO: This should be used by #getAvailableCaptureResultKeys.

    + + + + + HAL Implementation Details + + + +

    Tags listed here must always have an entry in the result metadata, +even if that size is 0 elements. Only array-type tags (e.g. lists, +matrices, strings) are allowed to have 0 elements.

    +

    Vendor tags must not be listed here. Use the vendor tag metadata +extensions C api instead (refer to camera3.h for more details).

    +

    Setting/getting vendor tags will be checked against the metadata +vendor extensions API and not against this field.

    +

    The HAL must not produce any result tags that are not listed either +here or in the vendor tag list.

    +

    The public camera2 API will always make the vendor tags visible +via CameraCharacteristics#getAvailableCaptureResultKeys.

    + + + + + + + + + + android.request.availableCharacteristicsKeys + + + int32 + x + + + n + + [hidden] + + + + + +

    A list of all keys that the camera device has available +to use with CameraCharacteristics.

    + + + + + + + + + + + + + + Details + + + +

    This entry follows the same rules as +android.request.availableResultKeys (except that it applies for +CameraCharacteristics instead of CaptureResult). See above for more +details.

    +

    TODO: This should be used by CameraCharacteristics#getKeys.

    + + + + + HAL Implementation Details + + + +

    Tags listed here must always have an entry in the static info metadata, +even if that size is 0 elements. Only array-type tags (e.g. lists, +matrices, strings) are allowed to have 0 elements.

    +

    Vendor tags must not be listed here. Use the vendor tag metadata +extensions C api instead (refer to camera3.h for more details).

    +

    Setting/getting vendor tags will be checked against the metadata +vendor extensions API and not against this field.

    +

    The HAL must not have any tags in its static info that are not listed +either here or in the vendor tag list.

    +

    The public camera2 API will always make the vendor tags visible +via CameraCharacteristics#getKeys.

    + + + + + + @@ -15446,7 +15859,7 @@ doesn't violate the above rules.

    - + android.info.supportedHardwareLevel @@ -15466,14 +15879,7 @@ doesn't violate the above rules.

    -

    The camera 3 HAL device can implement one of two possible -operational modes; limited and full. Full support is -expected from new higher-end devices. Limited mode has -hardware requirements roughly in line with those for a -camera HAL device v1 implementation, and is expected from -older or inexpensive devices. Full is a strict superset of -limited, and they share the same essential operational flow.

    -

    For full details refer to "S3. Operational Modes" in camera3.h

    +

    Generally classifies the overall set of the camera device functionality.

    @@ -15487,7 +15893,40 @@ limited, and they share the same essential operational flow.

    + + Details + + + +

    Camera devices will come in two flavors: LIMITED and FULL.

    +

    A FULL device has the most support possible and will enable the +widest range of use cases such as:

    + +

    A LIMITED device may have some or none of the above characteristics. +To find out more refer to android.request.availableCapabilities.

    + + + + HAL Implementation Details + + + +

    The camera 3 HAL device can implement one of two possible +operational modes; limited and full. Full support is +expected from new higher-end devices. Limited mode has +hardware requirements roughly in line with those for a +camera HAL device v1 implementation, and is expected from +older or inexpensive devices. Full is a strict superset of +limited, and they share the same essential operational flow.

    +

    For full details refer to "S3. Operational Modes" in camera3.h

    + + diff --git a/camera/docs/metadata_properties.xml b/camera/docs/metadata_properties.xml index 102a342d..e7581ec5 100644 --- a/camera/docs/metadata_properties.xml +++ b/camera/docs/metadata_properties.xml @@ -2731,6 +2731,272 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata the metadata via later partial results. + + + BACKWARD_COMPATIBLE + The minimal set of capabilities that every camera + device (regardless of android.info.supportedHardwareLevel) + will support. + + The full set of features supported by this capability makes + the camera2 api backwards compatible with the camera1 + (android.hardware.Camera) API. + + TODO: @hide this. Doesn't really mean anything except + act as a catch-all for all the 'base' functionality. + + + OPTIONAL + This is a catch-all capability to include all other + tags or functionality not encapsulated by one of the other + capabilities. + + A typical example is all tags marked 'optional'. + + TODO: @hide. We may not need this if we @hide all the optional + tags not belonging to a capability. + + + MANUAL_SENSOR + + The camera device can be manually controlled (3A algorithms such + as auto exposure, and auto focus can be + bypassed), this includes but is not limited to: + + * Manual exposure control + * android.sensor.exposureTime + * android.sensor.info.exposureTimeRange + * Manual sensitivity control + * android.sensor.sensitivity + * android.sensor.info.sensitivityRange + * android.sensor.baseGainFactor + * Manual lens control + * android.lens.* + * Manual flash control + * android.flash.* + * Manual black level locking + * android.blackLevel.lock + + If any of the above 3A algorithms are enabled, then the camera + device will accurately report the values applied by 3A in the + result. + + + GCAM + + TODO: This should be @hide + + * Manual tonemap control + * android.tonemap.curveBlue + * android.tonemap.curveGreen + * android.tonemap.curveRed + * android.tonemap.mode + * android.tonemap.maxCurvePoints + * Manual white balance control + * android.colorCorrection.transform + * android.colorCorrection.gains + * Lens shading map information + * android.statistics.lensShadingMap + * android.lens.info.shadingMapSize + + If auto white balance is enabled, then the camera device + will accurately report the values applied by AWB in the result. + + The camera device will also support everything in MANUAL_SENSOR + except manual lens control and manual flash control. + + + ZSL + + The camera device supports the Zero Shutter Lag use case. + + * At least one input stream can be used. + * RAW_OPAQUE is supported as an output/input format + * Using RAW_OPAQUE does not cause a frame rate drop + relative to the sensor's maximum capture rate (at that + resolution). + * RAW_OPAQUE will be reprocessable into both YUV_420_888 + and JPEG formats. + * The maximum available resolution for RAW_OPAQUE streams + (both input/output) will match the maximum available + resolution of JPEG streams. + + + DNG + + The camera device supports outputting RAW buffers that can be + saved offline into a DNG format. It can reprocess DNG + files (produced from the same camera device) back into YUV. + + * At least one input stream can be used. + * RAW16 is supported as output/input format. + * RAW16 is reprocessable into both YUV_420_888 and JPEG + formats. + * The maximum available resolution for RAW16 streams (both + input/output) will match the value in + android.sensor.info.pixelArraySize. + * All DNG-related optional metadata entries are provided + by the camera device. + + + + List of capabilities that the camera device + advertises as fully supporting. +
    + A capability is a contract that the camera device makes in order + to be able to satisfy one or more use cases. + + Listing a capability guarantees that the whole set of features + required to support a common use will all be available. + + Using a subset of the functionality provided by an unsupported + capability may be possible on a specific camera device implementation; + to do this query each of android.request.availableRequestKeys, + android.request.availableResultKeys, + android.request.availableCharacteristicsKeys. + + XX: Maybe these should go into android.info.supportedHardwareLevel + as a table instead? + + The following capabilities are guaranteed to be available on + android.info.supportedHardwareLevel `==` FULL devices: + + * MANUAL_SENSOR + * ZSL + + Other capabilities may be available on either FULL or LIMITED + devices, but the app. should query this field to be sure. +
    + + Additional constraint details per-capability will be available + in the Compatibility Test Suite. + + BACKWARD_COMPATIBLE capability requirements are not explicitly listed. + Instead refer to "BC" tags and the camera CTS tests in the + android.hardware.cts package. + + Listed controls that can be either request or result (e.g. + android.sensor.exposureTime) must be available both in the + request and the result in order to be considered to be + capability-compliant. + + For example, if the HAL claims to support MANUAL control, + then exposure time must be configurable via the request _and_ + the actual exposure applied must be available via + the result. + +     + + + n + + A list of all keys that the camera device has available + to use with CaptureRequest. + +
    Attempting to set a key into a CaptureRequest that is not + listed here will result in an invalid request and will be rejected + by the camera device. + + This field can be used to query the feature set of a camera device + at a more granular level than capabilities. This is especially + important for optional keys that are not listed under any capability + in android.request.availableCapabilities. + + TODO: This should be used by #getAvailableCaptureRequestKeys. +
    + + Vendor tags must not be listed here. Use the vendor tag metadata + extensions C api instead (refer to camera3.h for more details). + + Setting/getting vendor tags will be checked against the metadata + vendor extensions API and not against this field. + + The HAL must not consume any request tags that are not listed either + here or in the vendor tag list. + + The public camera2 API will always make the vendor tags visible + via CameraCharacteristics#getAvailableCaptureRequestKeys. + +     + + + n + + A list of all keys that the camera device has available + to use with CaptureResult. + +
    Attempting to get a key from a CaptureResult that is not + listed here will always return a `null` value. Getting a key from + a CaptureResult that is listed here must never return a `null` + value. + + The following keys may return `null` unless they are enabled: + + * android.statistics.lensShadingMap (non-null iff android.statistics.lensShadingMapMode == ON) + + (Those sometimes-null keys should nevertheless be listed here + if they are available.) + + This field can be used to query the feature set of a camera device + at a more granular level than capabilities. This is especially + important for optional keys that are not listed under any capability + in android.request.availableCapabilities. + + TODO: This should be used by #getAvailableCaptureResultKeys. +
    + + Tags listed here must always have an entry in the result metadata, + even if that size is 0 elements. Only array-type tags (e.g. lists, + matrices, strings) are allowed to have 0 elements. + + Vendor tags must not be listed here. Use the vendor tag metadata + extensions C api instead (refer to camera3.h for more details). + + Setting/getting vendor tags will be checked against the metadata + vendor extensions API and not against this field. + + The HAL must not produce any result tags that are not listed either + here or in the vendor tag list. + + The public camera2 API will always make the vendor tags visible + via CameraCharacteristics#getAvailableCaptureResultKeys. + +     + + + n + + A list of all keys that the camera device has available + to use with CameraCharacteristics. +
    This entry follows the same rules as + android.request.availableResultKeys (except that it applies for + CameraCharacteristics instead of CaptureResult). See above for more + details. + + TODO: This should be used by CameraCharacteristics#getKeys. +
    + + Tags listed here must always have an entry in the static info metadata, + even if that size is 0 elements. Only array-type tags (e.g. lists, + matrices, strings) are allowed to have 0 elements. + + Vendor tags must not be listed here. Use the vendor tag metadata + extensions C api instead (refer to camera3.h for more details). + + Setting/getting vendor tags will be checked against the metadata + vendor extensions API and not against this field. + + The HAL must not have any tags in its static info that are not listed + either here or in the vendor tag list. + + The public camera2 API will always make the vendor tags visible + via CameraCharacteristics#getKeys. + +
    @@ -4430,6 +4696,24 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata FULL + Generally classifies the overall set of the camera device functionality. + + Optional. Default value is LIMITED. +
    + Camera devices will come in two flavors: LIMITED and FULL. + + A FULL device has the most support possible and will enable the + widest range of use cases such as: + + * 30 FPS at maximum resolution (== sensor resolution) + * Per frame control + * Manual sensor control + * Zero Shutter Lag (ZSL) + + A LIMITED device may have some or none of the above characteristics. + To find out more refer to android.request.availableCapabilities. +
    + The camera 3 HAL device can implement one of two possible operational modes; limited and full. Full support is expected from new higher-end devices. Limited mode has @@ -4439,8 +4723,7 @@ xsi:schemaLocation="http://schemas.android.com/service/camera/metadata/ metadata limited, and they share the same essential operational flow. For full details refer to "S3. Operational Modes" in camera3.h - - Optional. Default value is LIMITED. +
    diff --git a/camera/include/system/camera_metadata_tags.h b/camera/include/system/camera_metadata_tags.h index 86063370..65d446ad 100644 --- a/camera/include/system/camera_metadata_tags.h +++ b/camera/include/system/camera_metadata_tags.h @@ -253,6 +253,10 @@ typedef enum camera_metadata_tag { ANDROID_REQUEST_PIPELINE_DEPTH, // byte | public ANDROID_REQUEST_PIPELINE_MAX_DEPTH, // byte | public ANDROID_REQUEST_PARTIAL_RESULT_COUNT, // int32 | public + ANDROID_REQUEST_AVAILABLE_CAPABILITIES, // enum | public + ANDROID_REQUEST_AVAILABLE_REQUEST_KEYS, // int32[] | hidden + ANDROID_REQUEST_AVAILABLE_RESULT_KEYS, // int32[] | hidden + ANDROID_REQUEST_AVAILABLE_CHARACTERISTICS_KEYS, // int32[] | hidden ANDROID_REQUEST_END, ANDROID_SCALER_CROP_REGION = // int32[] | public @@ -642,6 +646,16 @@ typedef enum camera_metadata_enum_android_request_type { ANDROID_REQUEST_TYPE_REPROCESS, } camera_metadata_enum_android_request_type_t; +// ANDROID_REQUEST_AVAILABLE_CAPABILITIES +typedef enum camera_metadata_enum_android_request_available_capabilities { + ANDROID_REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE, + ANDROID_REQUEST_AVAILABLE_CAPABILITIES_OPTIONAL, + ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR, + ANDROID_REQUEST_AVAILABLE_CAPABILITIES_GCAM, + ANDROID_REQUEST_AVAILABLE_CAPABILITIES_ZSL, + ANDROID_REQUEST_AVAILABLE_CAPABILITIES_DNG, +} camera_metadata_enum_android_request_available_capabilities_t; + // ANDROID_SCALER_AVAILABLE_FORMATS typedef enum camera_metadata_enum_android_scaler_available_formats { diff --git a/camera/src/camera_metadata_tag_info.c b/camera/src/camera_metadata_tag_info.c index 60b1f320..2d1fba77 100644 --- a/camera/src/camera_metadata_tag_info.c +++ b/camera/src/camera_metadata_tag_info.c @@ -379,6 +379,14 @@ static tag_info_t android_request[ANDROID_REQUEST_END - { "pipelineMaxDepth", TYPE_BYTE }, [ ANDROID_REQUEST_PARTIAL_RESULT_COUNT - ANDROID_REQUEST_START ] = { "partialResultCount", TYPE_INT32 }, + [ ANDROID_REQUEST_AVAILABLE_CAPABILITIES - ANDROID_REQUEST_START ] = + { "availableCapabilities", TYPE_BYTE }, + [ ANDROID_REQUEST_AVAILABLE_REQUEST_KEYS - ANDROID_REQUEST_START ] = + { "availableRequestKeys", TYPE_INT32 }, + [ ANDROID_REQUEST_AVAILABLE_RESULT_KEYS - ANDROID_REQUEST_START ] = + { "availableResultKeys", TYPE_INT32 }, + [ ANDROID_REQUEST_AVAILABLE_CHARACTERISTICS_KEYS - ANDROID_REQUEST_START ] = + { "availableCharacteristicsKeys", TYPE_INT32 }, }; static tag_info_t android_scaler[ANDROID_SCALER_END - @@ -1590,6 +1598,46 @@ int camera_metadata_enum_snprint(uint32_t tag, case ANDROID_REQUEST_PARTIAL_RESULT_COUNT: { break; } + case ANDROID_REQUEST_AVAILABLE_CAPABILITIES: { + switch (value) { + case ANDROID_REQUEST_AVAILABLE_CAPABILITIES_BACKWARD_COMPATIBLE: + msg = "BACKWARD_COMPATIBLE"; + ret = 0; + break; + case ANDROID_REQUEST_AVAILABLE_CAPABILITIES_OPTIONAL: + msg = "OPTIONAL"; + ret = 0; + break; + case ANDROID_REQUEST_AVAILABLE_CAPABILITIES_MANUAL_SENSOR: + msg = "MANUAL_SENSOR"; + ret = 0; + break; + case ANDROID_REQUEST_AVAILABLE_CAPABILITIES_GCAM: + msg = "GCAM"; + ret = 0; + break; + case ANDROID_REQUEST_AVAILABLE_CAPABILITIES_ZSL: + msg = "ZSL"; + ret = 0; + break; + case ANDROID_REQUEST_AVAILABLE_CAPABILITIES_DNG: + msg = "DNG"; + ret = 0; + break; + default: + msg = "error: enum value out of range"; + } + break; + } + case ANDROID_REQUEST_AVAILABLE_REQUEST_KEYS: { + break; + } + case ANDROID_REQUEST_AVAILABLE_RESULT_KEYS: { + break; + } + case ANDROID_REQUEST_AVAILABLE_CHARACTERISTICS_KEYS: { + break; + } case ANDROID_SCALER_CROP_REGION: { break; -- 2.11.0