Bewerken

Delen via

Capture Stats Metadata Attributes

  • Artikel

The table below summarizes the available capture stats IMFAttributes for the MFT0's MFSampleExtension_CaptureMetaData metadata attribute bag for preview, video, and still capture.

The capture stats listed for still is mandatory for every photo captured unless otherwise indicated. The capture stats listed for preview and video should be delivered as the best effort and the driver may or may not deliver all capture stats on all frames based on the availability and performance considerations.

Name Type Pin Description
MF_CAPTURE_METADATA_FOCUSSTATE UINT32 Preview This attribute contains the current focus state which can take one of the following values.
MF_CAPTURE_METADATA_SENSORFRAMERATE UINT64 Preview This attribute contains the measured sensor readout rate in hertz when a preview frame is captured, which consists of a numerator value in the upper 32 bit and a denominator value in the lower 32 bit.
MF_CAPTURE_METADATA_FACEROIS Blob Preview, Video This attribute contains the face rectangle info detected by the driver.
MF_CAPTURE_METADATA_FACEROITIMESTAMPS Blob Preview, Video This attribute contains the time stamp info for the face ROIs identified in MF_CAPTURE_METADATA_FACEROIS.
MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS Blob Preview, Video This attribute contains the blink and\or facial expression state for the face ROIs identified in MF_CAPTURE_METADATA_FACEROIS. 
MF_CAPTURE_METADATA_EXPOSURE_TIME UINT64 Preview, Still This attribute contains the exposure time applied in 100 nanoseconds
MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION Blob Preview, Still This attribute contains an EV compensation step flag and an EV compensation value in units of the step that was applied to the driver when the photo was captured.
MF_CAPTURE_METADATA_ISO_SPEED UINT32 Preview, Still This attribute contains the ISO speed value applied as an integer.
MF_CAPTURE_METADATA_LENS_POSITION UINT32 Preview, Still This attribute contains the logical lens position when focus was applied to the photo captured. This value does not have a specific unit.
MF_CAPTURE_METADATA_SCENE_MODE UINT64 Still This attribute contains the scene mode applied as a UINT64KSCAMERA_EXTENDEDPROP_SCENEMODE_XXX flag.
MF_CAPTURE_METADATA_FLASH UINT32 (Boolean) Preview, Still This attribute contains a Boolean value that contains the flash state. A value of 1 specifies that the flash is on and a value of 0 specifies that the flash is off for the photo captured.
MF_CAPTURE_METADATA_FLASH_POWER UINT32 Still [Optional] This attribute contains the flash power applied as a percentage value between 0 and 100.
MF_CAPTURE_METADATA_WHITEBALANCE UINT32 (Kelvin) Preview, Still This attribute contains the white balance applied as a value in Kelvin.
MF_CAPTURE_METADATA_ZOOMFACTOR UINT32 (Q16) Still This attribute contains the zoom value applied and is the same value that can be queried from KSPROPERTY_CAMERACONTROL_EXTENDED_ZOOM in a GET call. The value must be in Q16.
MF_CAPTURE_METADATA_EXIF Blob Still [Optional] This attribute contains EXIF metadata as specified in the blob definition section
MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID UINT32 Still [Optional] This attribute contains the frame ID for the corresponding frame in the variable photo sequence. This attribute is only set for a variable photo sequence capture.
MF_CAPTURE_METADATA_ISO_GAINS Blob Preview This attribute contains the analog and digital gains applied to the senor when the preview frame was captured. This is unitless.
MF_CAPTURE_METADATA_WHITEBALANCE_GAINS Blob Preview This attribute contains the white balance gains applied to R, G, B by the sensor and\or ISP when the preview frame was captured. This is a unitless.
MF_CAPTURE_METADATA_HISTOGRAM Blob Preview This attribute contains the histogram when apreview frame is captured.
MF_CAPTURE_METADATA_FRAME_ILLUMINATION UINT64 IR Pin used for Hello This attribute for IR cameras specifies whether the frames are using active IR illumination and should be used in conjunction with FACEAUTH_MODE_ALTERNATIVE_FRAME_ILLUMINATION.
Any Custom GUID Any variant type This attribute contains the custom data associated with the custom GUID

MF_CAPTURE_METADATA_FOCUSSTATE

MF_CAPTURE_METADATA_FOCUSSTATE attribute contains the current focus state which can take one of the following values.

typedef enum
{
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_UNINITIALIZED = 0,
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_LOST,
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_SEARCHING,
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_FOCUSED,
    KSCAMERA_EXTENDEDPROP_FOCUSSTATE_FAILED,
} KSCAMERA_EXTENDEDPROP_FOCUSSTATE;

MF_CAPTURE_METADATA_SENSORFRAMERATE

MF_CAPTURE_METADATA_SENSORFRAMERATE attribute contains the measured sensor readout rate in hertz when a preview frame is captured, which consists of a numerator value in the upper 32 bit and a denominator value in the lower 32 bit.

MF_CAPTURE_METADATA_FACEROIS

MF_CAPTURE_METADATA_FACEROIS attribute contains the face rectangle info detected by the driver. By default driver\MFT0 should provide the face info on preview stream. If driver advertises the capability on other streams, driver\MFT must provide the face info on the corresponding streams if the application enables face detection on those streams. When video stabilization is enabled on driver, the face info should be provided post the video stabilization. The data structures below describe the blob format for MF_CAPTURE_METADATA_FACEROIS. The dominate face must be the first FaceRectInfo in the blob.

typedef struct tagFaceRectInfoBlobHeader
{
    ULONG Size;             // Size of this header + all FaceRectInfo following
    ULONG Count;            // Number of FaceRectInfo’s in the blob
} FaceRectInfoBlobHeader;

typedef struct tagFaceRectInfo
{
    RECT Region;            // Relative coordinates on the frame that face detection is running (Q31 format)
    LONG ConfidenceLevel;   // Confidence level of the region being a face ([0, 100])
} FaceRectInfo;

Note that FaceRectinfoBlobHeader and FaceRectInfo structs only describe the blob format for the MF_CAPTURE_METADATA_FACEROIS attribute. The metadata item structure for face ROIs (KSCAMERA_METADATA_ITEMHEADER + face ROIs metadata payload) is up to driver and must be 8-byte aligned.

By design, if a stream is configured with face detection enabled and the scene in question does not contain any faces during capture, the driver is still required to attach a “dummy” MF_CAPTURE_METADATA_FACEROIS attribute to each sample which has no face information associated with it. (A “dummy” face ROI attribute has the Count field of the FaceRectInfoBlobHeader structure set to zero.)

MF_CAPTURE_METADATA_FACEROITIMESTAMPS

MF_CAPTURE_METADATA_FACEROITIMESTAMPS attribute contains the time stamp info for the face ROIs identified in MF_CAPTURE_METADATA_FACEROIS. For the device that cannot provide the time stamp for face ROIs, this attribute should be omitted.

The data structure below describes the blob format for MF_CAPTURE_METADATA_FACEROITIMESTAMPS.

typedef struct tagMetadataTimeStamps
{
    ULONG Flags;            // Bitwise OR of MF_METADATATIMESTAMPS_XXX flags
    LONGLONG Device;        // QPC time for the sample where the face rect is derived from (in 100ns)
    LONGLONG Presentation;  // PTS for the sample where the face rect is derived from (in 100ns)
} MetadataTimeStamps;

For Flags field, we will define the following bit flags to indicate which time stamp is valid. MFT0 must set Flags to MF_METADATATIEMSTAMPS_DEVICE and the appropriate QPC time for Device, if the driver provides the timestamp metadata for the face ROIs.

#define MF_METADATATIMESTAMPS_DEVICE 0x00000001

#define MF_METADATATIMESTAMPS_PRESENTATION 0x00000002

Note that MetadataTimeStamps struct only describes the blob format for the MF_CAPTURE_METADATA_FACEROITIMESTAMPS attribute. The metadata item structure for timestamp (KSCAMERA_METADATA_ITEMHEADER + timestamp metadata payload) is up to driver and must be 8-byte aligned.

MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS

MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS attribute contains the blink and\or facial expression state for the face ROIs identified in MF_CAPTURE_METADATA_FACEROIS.  For the device that doesn’t support blink and\or facial expression detection, this attribute should be omitted.

The data structure below describes the blob format for MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS.

Note that FaceCharacterizationBlobHeader and FaceCharacterization structs only describe the blob format for the MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS attribute. The metadata item structure for the face characterizations (KSCAMERA_METADATA_ITEMHEADER + face characterizations metadata payload) is up to driver and must be 8-byte aligned.

typedef struct tagFaceCharacterizationBlobHeader
{
    ULONG Size;     // Size of this header + all FaceCharacterization following
    ULONG Count;    // Number of FaceCharacterization’s in the blob. Must match the number of FaceRectInfo’s in FaceRectInfoBlobHeader
} FaceCharacterizationBlobHeader;

typedef struct tagFaceCharacterization
{
    ULONG BlinkScoreLeft;   // [0, 100]. 0 indicates no blink for the left eye. 100 indicates definite blink for the left eye
    ULONG BlinkScoreRight;  // [0, 100]. 0 indicates no blink for the right eye. 100 indicates definite blink for the right eye
    ULONG FacialExpression; // Any one of the MF_METADATAFACIALEXPRESSION_XXX defined
    ULONG FacialExpressionScore; // [0, 100]. 0 indicates no such facial expression as identified. 100 indicates definite such facial expression as defined
} FaceCharacterization;

The following defines the possible facial expression that can be detected.  

#define MF_METADATAFACIALEXPRESSION_SMILE             0x00000001

If MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS attribute presents, the number and the order of FaceCharacterization entries in its blob must match the number and the order of the FaceRectInfo entries in the blob of MF_CAPTURE_METADATA_FACEROIS.   Each FaceCharacterization entry represents the blink and\or facial expression state of the face in the corresponding FaceRectInfo entry at the same index.

The figure below illustrates the layouts of a face characterizations blob and a face ROIs blob of four faces with the first one neither blinking nor smiling, the second one blinking left eye, the third one smiling, and the fourth one both blinking (both eyes) and smiling.

MF_CAPTURE_METADATA_EXPOSURE_TIME

MF_CAPTURE_METADATA_EXPOSURE_TIME attribute contains the exposure time applied to the sensor when preview and\or photo frame was captured which is a UINT64 and is in 100ns.

MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION

MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION attribute contains an EV compensation step flag and an EV Compensation value in units of the step applied to the sensor when preview and\or photo frame was captured.

The data structure below describes the blob format for MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION.

typedef struct tagCapturedMetadataExposureCompensation
{
    UINT64 Flags;   // KSCAMERA_EXTENDEDPROP_EVCOMP_XXX step flag
    INT32 Value;    // EV Compensation value in units of the step
} CapturedMetadataExposureCompensation;

Note that CapturedMetadataExposureCompensation struct only describes the blob format for the MF_CAPTURE_METADATA_EXPOSURE_COMPENSATION attribute. The metadata item structure for EV compensation (KSCAMERA_METADATA_ITEMHEADER + EV compensation metadata payload) is up to driver and must be 8-byte aligned.

MF_CAPTURE_METADATA_ISO_SPEED

MF_CAPTURE_METADATA_ISO_SPEED attributes contains the ISO speed value applied to the sensor when preview and\or photo frame was captured. This is unitless.

MF_CAPTURE_METADATA_ISO_GAINS

MF_CAPTURE_METADATA_ISO_GAINS attribute contains the analog and digital gains applied to the senor when the preview frame was captured. This is unitless.

The data structure below describes the blob format for MF_CAPTURE_METADATA_ISO_GAINS.

typedef struct tagCapturedMetadataISOGains
{
    FLOAT AnalogGain;
    FLOAT DigitalGain;
} CapturedMetadataISOGains;

Note that CapturedMetadataISOGains struct only describes the blob format for the MF_CAPTURE_METADATA_ISO_GAINS attribute. The metadata item structure for ISO gains (KSCAMERA_METADATA_ITEMHEADER + ISO gains metadata payload) is up to driver and must be 8-byte aligned.

MF_CAPTURE_METADATA_LENS_POSITION

MF_CAPTURE_METADATA_LENS_POSITION attribute contains the logical lens position when preview and\or photo frame was captured, which is unitless. This is the same value that can be queried from KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUS in a GET call.

MF_CAPTURE_METADATA_SCENE_MODE

MF_CAPTURE_METADATA_SCENE_MODE attribute contains the scene mode applied to the photo captured which is a 64bit KSCAMERA_EXTENDEDPROP_SCENEMODE_XXX flag.

MF_CAPTURE_METADATA_FLASH

MF_CAPTURE_METADATA_FLASH attribute contains a boolean value when preview and\or photo frame was captured, with 1 meaning flash on and 0 meaning flash off.

MF_CAPTURE_METADATA_FLASH_POWER

MF_CAPTURE_METADATA_FLASH_POWER attribute contains the flash power applied to the photo captured which is a value in the range of [0, 100]. This attribute should be omitted if the driver does not support adjustable power for flash.

MF_CAPTURE_METADATA_WHITEBALANCE

MF_CAPTURE_METADATA_WHITEBALANCE attribute contains the white balance applied to the sensor when preview and\or photo frame was captured, which is a value in Kevin.

MF_CAPTURE_METADATA_WHITEBALANCE_GAINS

MF_CAPTURE_METADATA_WHITEBALANCE_GAINS attribute contains the white balance gains applied to R, G, B by the sensor and\or ISP when the preview frame was captured. This is a unitless.

The data structure below describes the blob format for MF_CAPTURE_METADATA_WHITEBALANCE_GAINS.

typedef struct tagCapturedMetadataWhiteBalanceGains
{
    FLOAT R;
    FLOAT G;
    FLOAT B;
} CapturedMetadataWhiteBalanceGains;

Note that CapturedMetadataWhiteBalanceGains struct only describes the blob format for the MF_CAPTURE_METADATA_WHITEBALANCE_GAINS attribute. The metadata item structure for white balance gains (KSCAMERA_METADATA_ITEMHEADER + white balance gains metadata payload) is up to driver and must be 8-byte aligned.

MF_CAPTURE_METADATA_ZOOMFACTOR

MF_CAPTURE_METADATA_ZOOMFACTOR attribute contains the zoom value applied to the photo captured which is the same value that can be queried from KSPROPERTY_CAMERACONTROL_EXTENDED_ZOOM in a GET call. This should be in Q16.

MF_CAPTURE_METADATA_EXIF

MF_CAPTURE_METADATA_EXIF contains EXIF metadata as specified in Section 3.1 (Blob definition). MFT0 shall extract the raw EXIF metadata, which is identified as a custom metadata item (MetadataId >= MetadataId_Custom_Start), from the MF_CAPTURE_METADATA_FRAME_RAWSTREAM buffer provided by the driver. MFT0 shall then convert the raw data into a MF_CAPTURE_METADATA_EXIF attribute.

Blob definition

The blob shall consist of a complete TIFF header, 0th IFD and EXIF sub-IFD as defined by the EXIF 2.3 and TIFF 6.0 specifications. The blob shall not contain any data before the TIFF header. The blob shall not contain any data after the end of the 0th IFD. For example, it is not valid to include an IFD containing thumbnail data.

The following diagram, copied from the TIFF specification, illustrates the expected memory layout:

EXIF blob definition.

The following are requirements that are consistent with the EXIF and TIFF specifications but are called out for emphasis:

  • The byte order shall be either little endian (“II”) or big endian(“MM”).
  • Pointers (“byte offsets” in the TIFF specification) shall be relative to the beginning of the TIFF header.

The following are requirements that are more restrictive than the EXIF and TIFF specifications:

  • The offset to the next IFD shall be 0, i.e. no additional IFDs are pointed to.
  • The TIFF header and 0th IFD shall be contiguous, i.e. the offset to the 0th IFD as stored in bytes 4-7 shall be 0x8.

Mandatory EXIF metadata

The section below describes EXIF metadata that must be included in MF_CAPTURE_METADATA_EXIF .

Name EXIF Tag Description
Orientation 274 Image orientation viewed in terms of rows and columns. See EXIF spec for complete description
Make 271 The manufacturer of the recording equipment
Model 272 The model name or the model number of the device
XResolution 282 The number of pixels per resolution unit in the ImageWidth direction
YResolution 283 The number of pixels per resolution unit in the ImageLength direction
ResolutionUnit 296 The unit for measuring XResolution and YResolution
Software 305 Name and version of the firmware
ColorSpace 40961 The color space information, typically sRGB
SubsSecTimeOriginal 37521 Records fractions of seconds associated with DateTimeOriginal tag
SubSecTimeDigitized 37522 Records fractions of seconds associated with DateTimeDigitized tag
ExposureTime 33434 Exposure time in seconds (accurate to 0.001s)
FNumber 33437 The F number used for capture
ISOSpeedRatings 34855 ISO speed value as defined in ISO 12322, saturation based
DateTimeOriginal 36867 Date and time when the original image data was generated
DateTimeDIgitized 36868 The date and time when theimage as stored as digital data
Shutter SpeedValue 37377 Shutter speed in Additive System of Photographic Exposure (APEX) units
Aperture Value 37378 The lens aperture in APEX units
ExposureBias Value 37380 Exposure Bias value in APEX units
MeteringMode 37383 AE metering mode (see EXIF spec)
LightSource 37384 The kind of light source (see EXIF spec)
Flash 37385 Status of the flash during image capture
FocalLength 37386 The actual focal length of the lens
ExposureMode 41986 Exposure Mode during capture
WhiteBalance 41987 White balance mode during capture
DigitalZoomRatio 41988 Digital zoom ratio during image capture
FocalLengthIn35mmFilm 41989 35 mm equivalent focal length
SceneCaptureType 41990 Type of scene that was shot

Optional/OEM-defined metadata

The camera driver may include any additional metadata in the form of custom EXIF tags as long as it conforms to the EXIF specification and is stored in either the 0th TIFF IFD or the EXIF sub-IFD.

MakerNote requirements and binary layout expectations

The camera driver may include manufacturer-proprietary information in the form of a maker note (tag 37500). The maker note must not contain any pointers to, or otherwise rely on, data that is outside of the maker note itself, including the start of the file and the position of the TIFF header. In addition, it must not make assumptions about the endianness of the file as specified in the TIFF header.

In general, the operating system makes no guarantees that the binary layout of the metadata blob is preserved when it is written to the output JPEG stream. It only guarantees that the metadata is written out in conformance with the EXIF specification. For example, it only guarantees that the maker note is copied as a contiguous block and is identified by the correct IFD tag, type, and offset.

Usage with WIC JPEG encoder

The intended usage of MF_CAPTURE_METADATA_EXIF is with the OS-provided Windows Imaging Component (WIC) JPEG encoder. Windows Camera pipeline uses the Windows WIC JPEG encoder to consume EXIF metadata obtained from MF_CAPTURE_METADATA_EXIF and muxes this with image pixel data into a JPEG file when the application is not capturing a JPEG directly from camera, but configured pipeline to capture to NV12/YUY2 and get encoded by the OS

MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID

MF_CAPTURE_METADATA_REQUESTED_FRAME_SETTING_ID attribute contains the frame ID for the corresponding frame in the variable photo sequence. This attribute is only set for a variable photo sequence capture.

MF_CAPTURE_METADATA_FRAME_ILLUMINATION

MF_CAPTURE_METADATA_FRAME_ILLUMINATION attribute for IR cameras specifies whether the frames is using active IR illumination and should be used in conjunction with FACEAUTH_MODE_ALTERNATIVE_FRAME_ILLUMINATION. It is only used for IR samples and should not be present on RGB frames if the camera supports both IR and color samples.

Value should be set to 0xXXXXXXXXXXXXXXX1 if frame was captured when active illumination was on and set to 0xXXXXXXXXXXXXXXX0 if no illumination was present when capturing the frame.

MF_CAPTURE_METADATA_HISTOGRAM

MF_CAPTURE_METADATA_HISTOGRAM attribute contains the histogram when apreview frame is captured.

The data structures below describe the blob format for MF_CAPTURE_METADATA_HISTOGRAM.

typedef struct tagHistogramGrid
{
    ULONG Width;    // Width of the sensor output that histogram is collected from
    ULONG Height;   // Height of the sensor output that histogram is collected from
    RECT Region;    // Absolute coordinates of the region on the sensor output that the histogram is collected for
} HistogramGrid;

typedef struct tagHistogramBlobHeader
{
    ULONG Size;         // Size of the entire histogram blob in bytes
    ULONG Histograms;   // Number of histograms in the blob. Each histogram is identified by a HistogramHeader
} HistogramBlobHeader;

typedef struct tagHistogramHeader
{
    ULONG Size;         // Size of this header + (HistogramDataHeader + histogram data following) * number of channels available
    ULONG Bins;         // Number of bins in the histogram
    ULONG FourCC;       // Color space that the histogram is collected from
    ULONG ChannelMasks; // Masks of the color channels that the histogram is collected for
    HistogramGrid Grid; // Grid that the histogram is collected from
} HistogramHeader;

typedef struct tagHistogramDataHeader
{
    ULONG Size;         // Size in bytes of this header + histogram data following
    ULONG ChannelMask;  // Mask of the color channel for the histogram data
    ULONG Linear;       // 1, if linear; 0 nonlinear
} HistogramDataHeader;

For ChannelMasks field, we will define the following bitmasks to indicate the available channels in the histogram.

#define MF_HISTOGRAM_CHANNEL_Y  0x00000001
#define MF_HISTOGRAM_CHANNEL_R  0x00000002
#define MF_HISTOGRAM_CHANNEL_G  0x00000004
#define MF_HISTOGRAM_CHANNEL_B  0x00000008
#define MF_HISTOGRAM_CHANNEL_Cb 0x00000010
#define MF_HISTOGRAM_CHANNEL_Cr 0x00000020

Notes:

  1. Each blob can contain multiple histograms collected from different regions or different color spaces of the same frame
  2. Each histogram in the blob is identified by its own HistogramHeader
  3. Each histogram has its own region and sensor output size associated. For full frame histogram, the region will match the sensor output size specified in HistogramGrid.
  4. Histogram data for all available channels are grouped under one histogram. Histogram data for each channel is identified by a HistogramDataHeader immediate above the data. ChannelMasks indicate how many and what channels are having the histogram data, which is the bitwise OR of the supported MF_HISTOGRAM_CHANNEL_XXX bitmasks as defined above. ChannelMask indicates what channel the data is for, which is identified by any one of the MF_HISTOGRAM_CHANNEL_XXX bitmasks defined above.

The figure below illustrates the layout of a histogram blob with a full frame Y-only histogram.

Histogram data is an array of ULONG with each entry representing the number of pixels falling under a set of tonal values as categorized by the bin. The data in the array should start from bin 0 to bin N-1, where N is the number of bins in the histogram, i.e., HistogramBlobHeader.Bins.

The figure below illustrates the layout of the histogram data section.

The figure below illustrates the layout of a histogram blob with a full-frame YRGB histogram with four channels.

The figure below illustrates the layout of a histogram blob with a Y-only histogram followed by a RGB histogram with three channels.

For Threshold, at minimum a full frame histogram with Y channel must be provided which should be the first histogram in the histogram blob, if KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM is supported.

Note that HistogramBlobHeader, HistogramHeader, HistogramDataHeader and Histogram data only describe the blob format for the MF_CAPTURE_METADATA_HISTOGRAM attribute. The metadata item structure for the histogram (KSCAMERA_METADATA_ITEMHEADER + all histogram metadata payload) is up to driver and must be 8-byte aligned.

Histogram Metadata Control

KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM is a property ID that will be used to control the histogram metadata produced by the driver. This is a pin level control for preview pin only and is defined as following:

typedef enum {
    …
#if (NTDDI_VERSION >= NTDDI_WIN8)
    KSPROPERTY_CAMERACONTROL_EXTENDED_HISTOGRAM
#endif
} KSPROPERTY_CAMERACONTROL_EXTENDED_PROPERTY;

For KSCAMERA_EXTENDEDPROP_HEADER, we will define the following bit flags to control the histogram metadata in driver. The default is OFF.

#define KSCAMERA_EXTENDEDPROP_HISTOGRAM_OFF 0x0000000000000000
#define KSCAMERA_EXTENDEDPROP_HISTOGRAM_ON  0x0000000000000001

This control must be used before the KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA control to ensure the proper sized metadata buffer is allocated.

If set to HISTOGRAM_OFF, the driver shall not deliver the histogram metadata on preview pin. The driver should not include the histogram metadata size in its metadata buffer size requirement.

If set to HISTOGRAM_ON, the driver shall deliver the histogram metadata on preview pin. The driver must include the histogram metadata size in its metadata buffer size requirement.

If the driver does not have the capability to produce histogram metadata, the driver should not implement this control. If the driver supports this control, it must also support KSPROPERTY_CAMERACONTROL_EXTENDED_METADATA control.

The SET call of this control has no effect when the preview pin is inany state higher than the KSSTATE_STOP state. The driver shall reject the SET call received if preview is not in the stop state and returns STATUS_INVALID_DEVICE_STATE. In a GET call, driver should return the current settings in Flags field.

This is a synchronous control. There are no capabilities defined for this control.

KSCAMERA_EXTENDEDPROP_HEADER

Version

Must be 1.

PinId

Must be the Pin ID associated with the preview pin.

Size

Must be sizeof(KSCAMERA_EXTENDEDPROP_HEADER) + sizeof(KSCAMERA_EXTENDEDPROP_VALUE)

Result

Indicates the error results of the last SET operation. If no SET operation has taken place, this must be 0.

Capability

Must be 0.

Flags

This is a read/write field. This can be any one of the KSCAMERA_EXTENDEDPROP_HISTOGRAM_XXX flags defined above.

KSCAMERA_EXTENDEDPROP_VALUE

Not used