Edit

KSPROPERTY_CAMERACONTROL_PERFRAMESETTING_CAPABILITY

  • Article

The KSPROPERTY_CAMERACONTROL_PERFRAMESETTING_CAPABILITY property ID that is defined in KSPROPERTY_CAMERACONTROL_PERFRAMESETTING_PROPERTY is used to get the per-frame capabilities from the driver. This is a GET only control; the driver must fail any SET calls.

Usage summary

To query per frame setting capability with the driver, the KSPROPERTY_CAMERACONTROL_PERFRAMESETTING_CAPABILITY property control is sent to the driver along with a data buffer. In a GET call, the driver fills the per frame setting capability payload in the data buffer provided using the format layout specified below.

The capability payload must start with a capability header. Each capability item must start with an item header. If a capability item has a payload, the item header must be followed by a corresponding item payload.

In a GET call, a zero length buffer is sent to the driver first to find out the required data buffer size to hold the entire capability payload. In response to the call, the driver must return STATUS_BUFFER_OVERFLOW with the required capability buffer size that must be at least the size of KSCAMERA_PERFRAMESETTING_CAP_HEADER.

The following are the descriptions of the KSCAMERA_PERFRAMESETTING_CAP_HEADER fields in context of the item types defined in the KSCAMERA_PERFRAMESETTING_ITEM_TYPE enumeration. The payload field represents the item payload structures after the KSCAMERA_PERFRAMESETTING_CAP_ITEM_HEADER structure.

Exposure time item

Size

This is the size of the KSCAMERA_PERFRAMESETTING_CAP_HEADER structure + the size of a KSPROPERTY_STEPPING_LONGLONG structure if manual mode is supported.

Type

This must be KSCAMERA_PERFRAMESETTING_ITEM_EXPOSURE_TIME.

Flags

This contains the available flags. This field must contain the flags available by doing a bit-wise OR of the flags defined in ksmedia.h.

#define KSCAMERA_PERFRAMESETTING_AUTO       0x0000000100000000
#define KSCAMERA_PERFRAMESETTING_MANUAL     0x0000000200000000

Payload

If the driver supports manual mode, a range payload must be specified in KSPROPERTY_STEPPING_LONGLONG.Bounds.SignedMinimum\SignedMaxmum and KSPROPERTY_STEPPING_LONGLONG.SteppingDelta

Flash item

Size

This is the size of the KSCAMERA_PERFRAMESETTING_CAP_HEADER structure.

Type

This must be KSCAMERA_PERFRAMESETTING_ITEM_TYPE.KSCAMERA_PERFRAMESETTING_ITEM_FLASH

Flags

This contains the available flags. This field must contain the flags available by doing a bit-wise OR of the FLASH flags defined below in ksmedia.h.

#define KSCAMERA_EXTENDEDPROP_FLASH_OFF                                 0x0000000000000000  
#define KSCAMERA_EXTENDEDPROP_FLASH_ON                                  0x0000000000000001  
#define KSCAMERA_EXTENDEDPROP_FLASH_ON_ADJUSTABLEPOWER                  0x0000000000000002  
#define KSCAMERA_EXTENDEDPROP_FLASH_AUTO                                0x0000000000000004  
#define KSCAMERA_EXTENDEDPROP_FLASH_AUTO_ADJUSTABLEPOWER                0x0000000000000008  
#define KSCAMERA_EXTENDEDPROP_FLASH_REDEYEREDUCTION                     0x0000000000000010

Payload

The flash item does not have a payload. If KSCAMERA_EXTENDEDPROP_FLASH_ON_ADJUSTABLEPOWER or KSCAMERA_EXTENDEDPROP_FLASH_AUTO_ADJUSTABLEPOWER is specified in the flags, the power parameter is in the range from 0 to 100.

Exposure compensation item

Size

This is the size of the KSCAMERA_PERFRAMESETTING_CAP_HEADER structure + the size of a KSPROPERTY_STEPPING_LONG structure if steps are supported.

Type

This must be KSCAMERA_PERFRAMESETTING_ITEM_TYPE.KSCAMERA_PERFRAMESETTING_ITEM_EXPOSURE_COMPENSATION

Flags

This contains the available flags. This field must contain the flags available by doing a bit-wise OR of the EVCOMP flags defined below in ksmedia.h or the AUTO flag defined below in ksmedia_phone.h.

#define KSCAMERA_PERFRAMESETTING_AUTO               0x0000000100000000
#define KSCAMERA_EXTENDEDPROP_EVCOMP_SIXTHSTEP      0x0000000000000001  
#define KSCAMERA_EXTENDEDPROP_EVCOMP_QUARTERSTEP    0x0000000000000002  
#define KSCAMERA_EXTENDEDPROP_EVCOMP_THIRDSTEP      0x0000000000000004  
#define KSCAMERA_EXTENDEDPROP_EVCOMP_HALFSTEP       0x0000000000000008  
#define KSCAMERA_EXTENDEDPROP_EVCOMP_FULLSTEP       0x0000000000000010

Payload

If a driver supports only auto mode, a payload is not included. Otherwise, a range payload must be specified in a KSPROPERTY_STEPPING_LONG structure. The min and max of EV compensation are absolute EV compensation values and are determined from KSPROPERTY_STEPPING_LONG.Bounds.SignedMinimum and KSPROPERTY_STEPPING_LONG.Bounds.SignedMaximum. The step of EV compensation is determined by the step size of the lowest EVCOMP step flag that corresponds to a float (for example, 1/6 for KSCAMERA_EXTENDEDPROP_EVCOMP_SIXTHSTEP).

ISO speed item

Size

This is the size of the KSCAMERA_PERFRAMESETTING_CAP_HEADER structure + the size of a KSPROPERTY_STEPPING_LONG structure if manual mode is supported.

Type

This must be KSCAMERA_PERFRAMESETTING_ITEM_TYPE.KSCAMERA_PERFRAMESETTING_ITEM_ISO

Flags

This field contains the available flags. This field must contain the flags available by doing a bit-wise OR of the ISO flags defined below in ksmedia.h and ksmedia_phone.h. If per-frame ISO is supported, the driver must support at least one of the following capabilities, ISO_AUTO and ISO_MANUAL, in which ISO_AUTO is mandatory. If ISO_MANUAL is advertised, the driver must further advertise the supported ISO speed min\max\step in KSPROPERTY_STEPPING_LONG.ISO_MANUAL must be supported if manual ISO is desired.

#define KSCAMERA_EXTENDEDPROP_ISO_MANUAL    0x0080000000000000

#define KSCAMERA_EXTENDEDPROP_ISO_AUTO      0x0000000000000001

Payload

If a driver supports only auto mode, a payload is not included. Otherwise, a range payload must be specified in a KSPROPERTY_STEPPING_LONG structure. The min, max, and step of ISO speeds are determined from KSPROPERTY_STEPPING_LONG.Bounds.UnsignedMinimum, KSPROPERTY_STEPPING_LONG.Bounds.UnsignedMaximum, and KSPROPERTY_STEPPING_LONG.Bounds.SteppingDelta. Drivers supporting integer manual ISO should only advertise ISO_MANUAL with supported ISO speed ranges (min/max/step). Numeric ISO_Xxx presets are not supported for per-frame ISO.

Focus item

Size

This is the size of the KSCAMERA_PERFRAMESETTING_CAP_HEADER structure + the size of a KSPROPERTY_STEPPING_LONG structure.

Type

This must be KSCAMERA_PERFRAMESETTING_ITEM_TYPE.KSCAMERA_PERFRAMESETTING_ITEM_FOCUS.

Flags

This contains the available flags. This field must be set by doing a bit-wise OR of the flag defined below in ksmedis.h.

#define KSCAMERA_PERFRAMESETTING_MANUAL     0x0000000200000000

Payload

A range payload must be specified in a KSPROPERTY_STEPPING_LONG structure. The min, max, and step of lens position are determined from KSPROPERTY_STEPPING_LONG.Bounds.UnsignedMinimum, KSPROPERTY_STEPPING_LONG.Bounds.UnsignedMaximum, and KSPROPERTY_STEPPING_LONG.SteppingDelta. The behavior of per-frame setting focus and how it interworks with global focus settings is defined as follows.

  1. Lens position is sticky; but focus commands are not. If continuous auto focus (CAF) has been selected in the global settings, the CAF operation is overridden only for the specified frames and CAF will likely move the lens position (likely after a full sweep) after provided manual focus.

  2. The global focus setting is always assumed unless explicitly overridden with a manual setting in PFS.

  3. The global AF is one-shot and only applies to the first frame, if no manual override was specified.

  4. The global CAF applies to all frames unless explicitly overridden by a PFS.

  5. The global manual focus settings do not revert after a manual PFS (the lens position remains).

Confirmation image type

Size

This is the size of the KSCAMERA_PERFRAMESETTING_CAP_HEADER structure.

Type

This must be KSCAMERA_PERFRAMESETTING_ITEM_TYPE.KSCAMERA_PERFRAMESETTING_ITEM_PHOTOCONFIRMATION.

Flags

The flags field is not used.

Payload

There is no payload for this item.

Custom property item

Size

This is the size of the KSCAMERA_PERFRAMESETTING_CAP_HEADER structure + the size of the GUID.

Type

This must be KSCAMERA_PERFRAMESETTING_ITEM_TYPE.KSCAMERA_PERFRAMESETTING_ITEM_CUSTOM.

Flags

The flags field is not used.

Payload

This is the custom property GUID.

Requirements

Header

 Ksmedia.h