KSPROPERTY_CAMERACONTROL_EXTENDED_FACEDETECTION

KSPROPERTY_CAMERACONTROL_EXTENDED_FACEDETECTION is a property ID that is used to turn on and off face detection.

Usage summary table

Scope	Control	Type
Version 1	Filter	Synchronous

The following flags can be placed in the KSCAMERA_EXTENDEDPROP_HEADER.Flags field to control face detection in the driver. By default, the driver should have FACEDETECTION_OFF.

#define KSCAMERA_EXTENDEDPROP_FACEDETECTION_OFF             0x0000000000000000
#define KSCAMERA_EXTENDEDPROP_FACEDETECTION_PREVIEW         0x0000000000000001
#define KSCAMERA_EXTENDEDPROP_FACEDETECTION_VIDEO           0x0000000000000002
#define KSCAMERA_EXTENDEDPROP_FACEDETECTION_PHOTO           0x0000000000000004
#define KSCAMERA_EXTENDEDPROP_FACEDETECTION_BLINK           0x0000000000000008
#define KSCAMERA_EXTENDEDPROP_FACEDETECTION_SMILE           0x0000000000000010

If the driver supports this control, it must support FACEDETECTION_OFF and any one of FACEDETECTION_PREVIEW, FACEDETECTION_VIDEO, or FACEDETECTION_PHOTO. The driver should further perform dominate face analysis and feed the dominate face to 3A directly when face detection is enabled.

If the driver does not support face detection, the driver should not implement this control.

The following table describes the flag capabilities.

Flag	Description
KSCAMERA_EXTENDEDPROP_FACEDETECTION_OFF	This is a mandatory capability. When specified, the face detection is disabled in the driver.
KSCAMERA_EXTENDEDPROP_FACEDETECTION_PREVIEW	This is an optional capability. When specified, the face detection is enabled in the driver and the driver must provide the face info, and the timestamp associated if supported, as a metadata through the preview pin. This flag is mutually exclusive with the OFF flag and can be used with the other flags.
KSCAMERA_EXTENDEDPROP_FACEDETECTION_VIDEO	This capability is optional. When specified, the face detection is enabled in the driver and the driver that supports such capability must provide the face info, and the timestamp associated if supported, as a metadata through the video pin. This flag is mutually exclusive with the OFF flag and can be used with the other flags.
KSCAMERA_EXTENDEDPROP_FACEDETECTION_PHOTO	This capability is optional. When specified, the face detection is enabled in the driver and the driver that supports such capability must provide the face info, and the timestamp associated if supported, as a metadata through the photo pin. This flag is mutually exclusive with the OFF flag and can be used with the other flags.
KSCAMERA_EXTENDEDPROP_FACEDETECTION_BLINK	This capability is optional. This flag can only be specified when PREVIEW, VIDEO, and\or PHOTO flags are specified. When specified, the driver that supports such capability must additionally provide the blink info as a metadata through the corresponding pin.
KSCAMERA_EXTENDEDPROP_FACEDETECTION_SMILE	This capability is optional. This flag can only be specified when PREVIEW, VIDEO, and\or PHOTO flags are specified. When specified, the driver that supports such capability must additionally provide the smile info as a metadata through the corresponding pin.

Note

MFT0 shall further attach the face information as a MF_CAPTURE_METADATA_FACEROIS, the timestamp as a MF_CAPTURE_METADATA_FACEROITIMESTAMPS, and the blink and/or smile information as a MF_CAPTURE_METADATA_FACEROICHARACTERIZATIONS on the sample. PREVIEW, VIDEO, and PHOTO capabilities are optional. However, at least one of PREVIEW, VIDEO, and PHOTO capabilities must be supported if this control is supported.

The following table contains the descriptions and requirements for the KSCAMERA_EXTENDEDPROP_HEADER structure fields when using the control.

Member	Description
Version	This must be 1.
PinId	Must be KSCAMERA_EXTENDEDPROP_FILTERSCOPE (0xFFFFFFFF).
Size	This must be sizeof(KSCAMERA_EXTENDEDPROP_HEADER) + sizeof(KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING).
Result	Indicates the error results of the last SET operation. If no SET operation has taken place, this must be 0.
Capability	Must be a bitwise OR of the supported KSCAMERA_EXTENDEDPROP_FACEDETECTION_* flags as defined above.
Flags	This is a read/write field. This can be a bit wise OR of the KSCAMERA_EXTENDEDPROP_FACEDETECTION_OFF/PREVIEW/VIDEO/PHOTO flags defined above, or a bit wise OR of KSCAMERA_EXTENDEDPROP_FACEDETECTION_BLINK and/or KSCAMERA_EXTENDEDPROP_FACEDETECTION_SMILE with any combinations of the KSCAMERA_EXTENDEDPROP_FACEDETECTION_PREVIEW/VIDEO/PHOTO flags.

The table below contains the descriptions and requirements for the KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING structure fields for the KSPROPERTY_CAMERACONTROL_EXTENDED_FACEDETECTION property. This structure is defined in Ksmedia.h.

Member	Description
Mode	Unused. Must be 0.
Min/Max/Step	The Min/Max/Step contains the minimum/maximum/increment of the number of faces that the camera driver can detect or search for in which Min must be >= 1 and Step must be 1. Driver must return these for GET operations.
VideoProc	If FACEDETECTION_PREVIEW, FACEDETECTION_VIDEO or FACEDETECTION_PHOTO are specified in the Flags field of the KSCAMERA_EXTENDEDPROP_HEADER, VideoProc.Value.ul must also specify the maximum number of the faces that the driver should search for. If FACEDETECTION_OFF is specified, for SET operations, the VideoProc field is ignored. For GET operations, the driver must return the maximum number of faces that the driver is currently searching for. If face detection is OFF, 0 should be returned.
Reserved	This is unused. This must be ignored by the driver.

Remarks

When face detection is turned on, the face region of interests (ROIs) can be consumed directly by the driver to aid 3A processing as needed. If any user specified ROIs are configured via KSPROPERTY_CAMERACONTROL_EXTENDED_ROI_ISPCONTROL at the same time, the user specified ROIs will take precedence over the face ROIs detected. If the user specified ROIs are cleared, the face ROIs detected will take effect.

Requirements

Header

Ksmedia.h