KSPROPERTY_CAMERACONTROL_PERFRAMESETTING_SET
The KSPROPERTY_CAMERACONTROL_PERFRAMESETTING_SET property ID that is defined in KSPROPERTY_CAMERACONTROL_PERFRAMESETTING_PROPERTY is used to set per-frame settings in the driver.
Usage summary
To set per frame settings, the KSPROPERTY_CAMERACONTROL_PERFRAMESETTING_SET property control is sent to the driver along with a per frame settings payload.
This property can be read or written. While a GET call can be used to return the last per frame settings that was set on the driver, the GET call is not exposed to the app client and is only issued at the initialization time when the per-frame setting control is constructed by the MF pipeline, where the driver must return STATUS_BUFFER_OVERFLOW with buffer size of 0.
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 per-frame settings the driver has. In response to this call, the driver must return STATUS_BUFFER_OVERFLOW with the required per-frame settings buffer size that must be 0 if no per-frame settings has ever been set or at least the size of KSCAMERA_PERFRAMESETTING_HEADER otherwise.
The per-frame setting payload must start with a KSCAMERA_PERFRAMESETTING_HEADER, followed by one or more frame settings. The number of frame settings is specified in FrameCount. The settings for each frame must start with a KSCAMERA_PERFRAMESETTING_FRAME_HEADER, followed by zero or more item settings. The number of item settings is specified in ItemCount. The settings for each item, if any must start with a KSCAMERA_PERFRAMESETTING_ITEM_HEADER.
For the settings for each item, if a Value payload is present, the KSCAMERA_PERFRAMESETTING_ITEM_HEADER must be followed by a KSCAMERA_EXTENDEDPROP_VALUE. If a custom item is present, KSCAMERA_PERFRAMESETTING_ITEM_HEADER must be followed by a KSCAMERA_PERFRAMESETTING_CUSTOM_ITEM, followed by the custom data associated with the GUID Id specified in KSCAMERA_PERFRAMESETTING_CUSTOM_ITEM.
If FrameCount is 0, the driver must reject the per-frame settings payload. If ItemCount is 0, no frame settings are specified. The driver must apply global settings to the frame associated. For example, FrameCount = 1 and ItemCount = 0 implies a single frame variable photo sequence with global settings.
The figure below illustrates the data structure layout of a per frame settings payload configuration. In the example below, a per-frame settings for four frames are configured with frame 0 containing three items, two without payload and one with a Value payload; frame 1 containing two items, one without payload and the other with a value payload; frame 2 containing 0 item which implies the global settings for frame 2; frame 3 containing four items, one with a value payload, two each with a custom item and a custom data payload, and one without payload.
Size in per-frame settings header represents the total payload size to be filled in KSCAMERA_PERFRAMESETTING_HEADER.Size
Size in per-frame settings frame represents the size to be filled in KSCAMERA_PERFRAMESETTING_FRAME_HEADER.Size for a frame.
Item size represents the size to be filled in KSCAMERA_PERFRAMESETTING_ITEM_HEADER.Size for an item.
Custom item size represents the size to be filled in KSCAMERA_PERFRAMESETTING_CUSTOM_ITEM.Size for a custom item.
Per-frame settings exposure time
If manual exposure time is specified in per frame settings, KSCAMERA_EXTENDEDPROP_VALUE.Value.ll will contain the desired exposure time in a SET call and the current exposure time in use in a GET call.
Per-frame settings compensation
If manual settings compensation is specified in per frame settings, KSCAMERA_EXTENDEDPROP_VALUE.Value.l will contain the desired exposure compensation in a SET call and the current exposure compensation in use in a GET call.
Per-frame settings focus
If manual per frame settings is specified in per frame settings, KSCAMERA_EXTENDEDPROP_VALUE.Value.ul will contain the desired lens position in a SET call and the current lens position in use in a GET call.
Per-frame settings ISO
If the driver does not support KSCAMERA_EXTENDEDPROP_ISO_MANUAL, the Value payload is not included. Otherwise, the per-frame setting item header must be followed by a KSCAMERA_EXTENDEDPROP_VALUE. In a SET call, KSCAMERA_EXTENDEDPROP_VALUE.Value.ul contains the desired ISO speed if KSCAMERA_EXTENDEDPROP_ISO_MANUAL is supported and specified in KSCAMERA_PERFRAMESETTING_ITEM_HEADER.Flags.
The following shows how the item header and Value payload should look like when the per-frame settings ISO capability is KSCAMERA_EXTNDEDPROP_ISO_AUTO, KSCAMERA_EXTENDEDPROP_ISO_MANUAL (min = 30, max = 210, step =20)as follows:
KSCAMERA_EXTNDEDPROP_ISO_AUTO,
KSCAMERA_EXTENDEDPROP_ISO_MANUAL (min = 30, max = 210, step =20)
If the ISO speed is 70
KSCAMERA_PERFRAMESETTING_ITEM_HEADER.Flags = KSCAMERA_EXTENDEDPROP_ISO_MANUAL KSCAMERA_EXTENDEDPROP_VALUE.Value.ul = 70If the ISO speed is 50
KSCAMERA_PERFRAMESETTING_ITEM_HEADER.Flags = KSCAMERA_EXTENDEDPROP_ISO_MANUAL KSCAMERA_EXTENDEDPROP_VALUE.Value.ul = 50
The following table summarizes the available controls and values for per-frame settings. The actual availability is determined by the driver's actual capability, which can be obtained using KSPROPERTY_CAMERACONTROL_PERFRAMESETTING_CAPABILITY.
| Name | Available values |
|---|---|
Exposure time |
Auto or time in 100 nanoseconds. |
Flash |
On/Off, auto, red eye reduction on/off, flash power in percentage. |
Exposure compensation |
Auto or compensation step value. |
ISO speed |
Auto or manual with integer ISO value. |
Focus |
Auto or logical lens position. This value does not have a specific unit. |
Custom properties |
The OEM defines this with a custom GUID and property data. |
Confirmation image |
On/Off |
To pass in the custom property data to the per-frame settings, the app does the following:
Calls the QueryInterface on IFrameSettingsControls to get the IMFGetServices interface that is associated with the per-frame settings.
Calls the GetService from the IMFGetServices interface to create a custom IMFAttributes interface on the per-frame settings.
Calls the SetUINT32, SetBlob, etc on the custom property GUID to set the custom property data on the IMFAttributes that is associated with the per-frame settings.
The framework will look up the custom IMFAttributes to construct the custom item payloads if any when assembling the per-frame settings payload to be set on the driver.
The LoopCount field in KSCAMERA_PERFRAMESETTING_HEADER specifies the number of repeats that the per-frame settings should be applied to the future frames to be captured in a photo sequence. The LoopCount is hard coded to 1 by the pipeline (for example, the per frame settings will be only applied once without further repeats). The FrameCount field in KSCAMERA_PERFRAMESETTING_HEADER specifies the number of frame settings that the per-frame settings should be applied to the frames in each repeat.
The ItemCount field in KSCAMERA_PERFRAMESETTING_FRAME_HEADER specifies the number of item settings that should be applied to the corresponding frame. If ItemCount is 0, global settings should be applied to the corresponding frame.
The table below lists the possible configurations and the corresponding photo sequence types.
| LoopCount | FrameCount | ItemCount | Type |
|---|---|---|---|
L(L=1) |
N(N>0) |
S(S>=0) |
Finite variable photo sequence |
L(L=1) |
1 |
0 |
One frame finite variable photo sequence with global settings |
L(L=1) |
0 |
S |
Invalid configuration |
The variable photo sequence has been simplified to perform finite captures with only one repeat. The photo sequence with per frame settings will be always flagged as a variable photo sequence and the per-frame settings payload is always required.
If the loop count is L (L = 1) and the frame count is N (N > 0), it is a finite variable photo sequence. The per-frame settings will be repeated L = 1 times with the N frame settings applied to the next N future frames in each repeat.
If the loop count is L (L = 1), the frame count is 1, and the item count is 0, it is a one frame finite variable photo sequence with global settings.
The variable photo sequence is further simplified to not request any past frames. The pipeline will hardcode the requested past photo count, (for example, RequestedHistoryFrames) to 0. The driver delivers only future frames in a variable photo sequence. The following figure illustrates the expected number of frames to be delivered by the driver in a variable photo sequence. The past photo count is specified in KSCAMERA_EXTENDEDPROP_PHOTOMODE.RequestedHistoryFrames by the KSPROPERTY_CAMERACONTROL_EXTENDED_PHOTOMODE extended property control that is hardcoded to 0 by the pipeline.
N : Frame Count
L : Loop Count
P : Past Photos Requested
T : Total number of frame delivered by driver
L = 1
P = 0
T = (N * L) + P
For the finite variable photo sequence, the driver must mark the KSSTREAM_HEADER.OptionsFlags for the last frame with the KSSTREAM_HEADER_OPTIONSF_ENDOFPHOTOSEQUENCE flag. Doing so will ensure that the driver automatically stops delivering frames back to the MF pipeline after the amount of future frames expected have been delivered. This effectively stops the photo sequence and notifies the app client of the completion of the photo sequence. This happens when driver finishes capturing the last frame in the finite variable photo sequence.
Requirements
Header |
Ksmedia.h |
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for