KS Data Formats and Data Ranges

KS pins specify data formats and ranges using the KSDATAFORMAT and KSDATARANGE structures. A data format specifies a single attribute of a data stream, for example an audio sampling size of 16 bits. A data range specifies multiple formats, for example an audio sampling range of 16-24 bits.

A minidriver includes an array of KSDATARANGE structures in each KSPIN_DESCRIPTOR structure that it provides. Microsoft-provided formats are enumerated in ksmedia.h.

A KSDATARANGE structure has the same members as a KSDATAFORMAT structure; however, the minidriver can specify wildcard values for the major format, subformat, and specifier members of KSDATARANGE.

Minidrivers use extended versions of these structures to define media-specific values. To read about how this works in audio and video capture, see: Audio Data Formats and Data Ranges and Selecting a Stream Format.

Clients use the following properties to query data format support of pins instantiated by a given pin factory on the filter:

• KSPROPERTY_PIN_DATARANGES. The KS filter reports all data ranges supported by pins instantiated by the pin factory. This includes every data format the pin can ever support.

• KSPROPERTY_PIN_CONSTRAINEDDATARANGES. The KS filter reports all data ranges supported by pins instantiated by the pin factory, given the current internal driver state.

• KSPROPERTY_PIN_PROPOSEDATAFORMAT. Clients can use this property to query if pins instantiated by the pin factory support a specific data format.

• KSPROPERTY_PIN_DATAINTERSECTION. Clients can use this property to offer a range of data formats.

Once a pin is instantiated, a user-mode client can determine the current data format or requests a change of data format through KSPROPSETID_Connection property requests. For example, the client uses KSPROPERTY_CONNECTION_PROPOSEDATAFORMAT to determine if a pin supports a given data format. The client uses KSPROPERTY_CONNECTION_DATAFORMAT to change the data format.

KS minidrivers and clients can dynamically negotiate data formats. When the data format of a stream changes, the minidriver specifies the KSSTREAM_HEADER_OPTIONSF_DATADISCONTINUITY flag in the OptionsFlags member of a KSSTREAM_HEADER. The minidriver passes the new data format itself, described in a KSDATAFORMAT structure, in the corresponding data buffer.