KSPROPERTY_CAMERACONTROL_EXTENDED_FOCUSMODE
The focus mode property controls the auto, manual, and preset focus modes of the camera.
Usage Summary Table
| Get | Set | Target | Property descriptor type | Property value type |
|---|---|---|---|---|
Yes |
Yes |
Filter |
The property value (operation data) contains a KSCAMERA_EXTENDEDPROP_HEADER structure and a KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING structure.
The total property data size is sizeof(KSCAMERA_EXTENDEDPROP_HEADER) + sizeof(KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING). The Size member of KSCAMERA_EXTENDEDPROP_HEADER is set to this total property data size.
The Capability member of KSCAMERA_EXTENDEDPROP_HEADER contains a bitwise OR combination of one or more of the following video processing options.
| Processing and focus mode | Description |
|---|---|
| KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_AUTO | Camera driver uses its own processing logic for video. |
| KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_MANUAL | Camera driver uses a preset processing method or a temperature based method. |
| KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_LOCK | The current video processing method is locked. |
| KSCAMERA_EXTENDEDPROP_FOCUS_CONTINUOUS | No converging focal point set. |
| KSCAMERA_EXTENDEDPROP_FOCUS_RANGE_MACRO | Macro range focal convergence. |
| KSCAMERA_EXTENDEDPROP_FOCUS_RANGE_NORMAL | Normal range focal convergence. |
| KSCAMERA_EXTENDEDPROP_FOCUS_RANGE_FULLRANGE | Full range focal convergence. |
| KSCAMERA_EXTENDEDPROP_FOCUS_RANGE_INFINITY | Infinite range focal convergence. |
| KSCAMERA_EXTENDEDPROP_FOCUS_RANGE_HYPERFOCAL | Hyperfocal range. |
The Flags member of KSCAMERA_EXTENDEDPROP_HEADER contains the video processing flag currently set for the camera. If KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_AUTO setting may be combined with KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_LOCK.
This property control is asynchronous and cancelable.
Remarks
Processing modes
KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_AUTO
This flag indicates that the auto focus operation has converged when the completion event is triggered. Upon completion, and when this flag is not a combined with KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_LOCK, the focus may diverge and the camera driver may continue to attempt convergence. If the KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_LOCK flag is included, the focus is locked to the first convergence and does not change until a new focus command is received.
Locking, without combining Auto mode, an already locked control should be treated as a no-op by the camera driver. Locking, in combination with Auto mode, an already locked control should trigger a new convergence.
This flag is mutually exclusive with the KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_MANUAL and KSCAMERA_EXTENDEDPROP_FOCUS_CONTINUOUS flags.
KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_MANUAL
Manual indicates that for this video processing, the specific values are provided. Specific values are provided to the driver.
This flag must not be combined with KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_AUTO, KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_LOCK, or KSCAMERA_EXTENDEDPROP_FOCUS_CONTINUOUS.
KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_LOCK
When this flag is set without a corresponding KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_AUTO flag, the camera driver is expected to lock the current focus state and trigger the completion event once the focus is locked. Camera driver must not vary the focus state until a new focus command is received. If KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_AUTO combined this flag, the camera driver will converge on auto-focus and lock the focus to that converged point and then trigger the completion event. This flag is must not be combined with KSCAMERA_EXTENDEDPROP_FOCUS_CONTINUOUS or KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_MANUAL.
This flag may not be specified with a range flag for the focus control unless it is combined with KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_AUTO. In that case, the focus is performed using the range flag to determine where to attempt the auto-focus scan. Then, upon convergence, the focus setting locks and the completion event fires.
KSCAMERA_EXTENDEDPROP_FOCUS_CONTINUOUS
This flag indicates that the focus is continuous. There is no single convergence point for focus control in this case. The driver must accept this request and complete the asynchronous operation immediately.
This flag must not be combined with KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_AUTO, KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_LOCK, or KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_MANUAL.
This mode is required for all drivers.
KSCAMERA_EXTENDEDPROP_FOCUS_RANGE_MACRO
This flag indicates that focus convergence should be performed for the macro range. The exact focal range is determined by the driver. This flag may be combined with KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_AUTO and KSCAMERA_EXTENDEDPROP_FOCUS_CONTINUOUS.
KSCAMERA_EXTENDEDPROP_FOCUS_RANGE_NORMAL
This flag indicates that focus convergence should be performed for the normal range. The exact focal range is determined by the driver. This flag may be combined with KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_AUTO and KSCAMERA_EXTENDEDPROP_FOCUS_CONTINUOUS.
KSCAMERA_EXTENDEDPROP_FOCUS_RANGE_FULLRANGE
This flag indicates that focus convergence should be performed for the full range. The exact focal range is determined by the driver. This flag may be combined with KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_AUTO and KSCAMERA_EXTENDEDPROP_FOCUS_CONTINUOUS.
This mode is required for all drivers.
KSCAMERA_EXTENDEDPROP_FOCUS_RANGE_INFINITY
This flag indicates that focus convergence should be performed for the infinite range. The exact focal range is determined by the driver. This flag may be combined with KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_AUTO and KSCAMERA_EXTENDEDPROP_FOCUS_CONTINUOUS.
KSCAMERA_EXTENDEDPROP_FOCUS_RANGE_HYPERFOCAL
This flag indicates that focus convergence should be performed for the hyperfocal range. The exact focal range is determined by the driver. This flag may be combined with KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_AUTO and KSCAMERA_EXTENDEDPROP_FOCUS_CONTINUOUS.
Getting the property
When responding to a KSPROPERTY_TYPE_GET request, the driver sets the members of the KSCAMERA_EXTENDEDPROP_HEADER to the following.
| Member | Value |
|---|---|
| Version | 1 |
| PinId | KSCAMERA_EXTENDEDPROP_FILTERSCOPE (0xFFFFFFFF). |
| Size | sizeof(KSCAMERA_EXTENDEDPROP_HEADER) + sizeof(KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING) |
| Result | 0 |
| Capability | KSCAMERA_EXTENDEDPROP_CAPS_ASYNCCONTROL | KSCAMERA_EXTENDEDPROP_CAPS_CANCELLABLE | (Video processing and focus modes supported) |
| Flags | The current video processing and focus mode. |
If no focus range flag previously set, then the driver sets Flags to KSCAMERA_EXTENDEDPROP_FOCUS_RANGE_FULLRANGE along with KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_AUTO (default). The members of the KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING structure that follows KSCAMERA_EXTENDEDPROP_HEADER are set according to the requirements of the focus mode.
The VideoProp.Value.ull value must contain the current exposure setting when the mode is KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_AUTO.
Setting the property
When the property is set, a KSPROPERTY_TYPE_SET request, the Flags member of KSCAMERA_EXTENDEDPROP_HEADER will contain the focus mode to set. The VideoProc.Value member of KSCAMERA_EXTENDEDPROP_VIDEOPROCSETTING must be ignored when Flags contains the KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_AUTO, KSCAMERA_EXTENDEDPROP_VIDEOPROCFLAG_LOCK, KSCAMERA_EXTENDEDPROP_FOCUS_CONTINUOUS flags.
Requirements
Version |
Available starting with Windows 8.1. |
Header |
Ksmedia.h (include Ksmedia.h) |
See also
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