Video Capture Property Sets

Video capture property sets group related properties of devices and streams. Whenever possible, minidrivers should implement the standard property sets defined in the ksmedia.h header file, such as KSPROPSETID_Pin and PROPSETID_ALLOCATOR_CONTROL. Minidrivers should avoid defining new property sets if one of the standard property sets provides the same functionality.

User-mode applications typically call COM interfaces to control property settings. The COM interface then sends and receives stream and adapter property sets to the minidriver through the Win32 DeviceIoControl API. The reference page for each property set describes the COM interface that user-mode applications call to control the kernel streaming properties of that set.

Depending on which kernel streaming interface a minidriver uses (AVStream or the Stream class), the minidriver specifies the video capture property sets that it supports differently. For example, if a minidriver uses the AVStream interface, then it specifies its properties in a recursive hierarchy encapsulated in a KSPROPERTY_SET structure. If the minidriver uses the Stream class interface, then it specifies its properties in an HW_STREAM_HEADER structure. Microsoft defines several macros that driver developers can use to specify the properties that their minidriver supports, regardless of which kernel streaming interface their minidriver uses.

For more information about how to support properties and property sets if your minidriver uses the AVStream interface, see the AVStream Filter-Centric Simulated Capture Driver (Avssamp) and AVStream Simulated Hardware Sample Driver (AVSHwS) sample minidrivers in the Windows driver samples repo on GitHub.

For more information about how to support properties and property sets if your minidriver uses the Stream Class interface, see Supporting Property Sets.

Hardware and stream property sets

Property sets are classified as belonging to either the hardware or to a specific stream. Hardware property sets apply to all devices and affect all streams. For example, PROPSETID_VIDCAP_CAMERACONTROL, which is used for camera positioning, affects all output streams and is therefore classified as a hardware property set. Note that some property sets, such as PROPSETID_VIDCAP_VIDEOCOMPRESSION, which controls the compression behavior of a single output stream, are implemented as a hardware property set that include an index to a specific stream. This method is required because stream property sets are unavailable when the pin is not connected. Hardware property sets are always available.

The following table lists the primary property sets used by video capture minidrivers. It also indicates whether the property set affects video capture hardware, or individual video capture streams. The list also indicates whether minidrivers are required to implement the property set.

Property set	Hardware property set	Video capture property set	Required
PROPSETID_ALLOCATOR_CONTROL		Y
PROPSETID_TUNER	Y
PROPSETID_VIDCAP_CAMERACONTROL	Y
PROPSETID_VIDCAP_CROSSBAR	Y
PROPSETID_VIDCAP_DROPPEDFRAMES		Y	Y
PROPSETID_VIDCAP_TVAUDIO	Y
PROPSETID_VIDCAP_VIDEOCOMPRESSION	Y
PROPSETID_VIDCAP_VIDEOCONTROL	Y
PROPSETID_VIDCAP_VIDEODECODER	Y
PROPSETID_VIDCAP_VIDEOPROCAMP	Y

At a minimum, a minidriver must report the number of frames dropped during capture as noted in the table above. Support for all other property sets is optional, depending on the capabilities of the device. It is strongly recommended that cameras, which offer only a limited set of capture frame rates, implement the PROPSETID_VIDCAP_VIDEOCONTROL to allow video conferencing applications to make optimal use of system bandwidth.

Property set default values and ranges

Properties can support default values and ranges. User-interface elements, such as sliders and scrollbars, use this information, as shown in the following image.

The default value and range information is provided in a KSPROPERTY_VALUES structure that is part of a property definition. This structure includes a pointer to a static table that consists of one or more KSPROPERTY_MEMBERSLIST structure instances. Within the KSPROPERTY_MEMBERSLIST structure, the minidriver can specify either a default value or a range of values. A range of values can be specified through the minimum, maximum, and stepping value. Set the MembersFlags member of the KSPROPERTY_MEMBERSHEADER structure to the KSPROPERTY_MEMBER_RANGES value to indicate that the KSPROPERTY_MEMBERSLIST structure is a range of values. A KSPROPERTY_MEMBERSLIST structure is also used to specify a default value for the property. This is done by setting the MembersFlags member of the KSPROPERTY_MEMBERSHEADER to the KSPROPERTY_MEMBER_VALUE value.