Microsoft DirectX 8.0

IAMStreamConfig Interface

The IAMStreamConfig interface is implemented on the output pins of audio/video capture filters and compression filters, including the VFW Capture Filter, the MJPEG Compressor, the ACM Wrapper, the Audio Capture Filter, and the AVI Compressor. Filter developers can implement this interface on any output pin that handles audio or video data.

This interface enables applications to query what types of formats a filter supports on its output pin, and to set the format that the pin will offer to its downstream connecting pin. This in turn enables an application to simply call IGraphBuilder::Render on the pin, and the graph builder will create a graph appropriate to the desired format.

Note  If an application attempts to use IPin::EnumMediaTypes to enumerate a pin's supported media types after calling SetFormat, only the one media type will be returned.

The IAMStreamConfig::GetStreamCaps method retrieves the AM_MEDIA_TYPE structure associated with the stream, as well as a VIDEO_STREAM_CONFIG_CAPS or an AUDIO_STREAM_CONFIG_CAPS structure that further describes the stream's characteristics. For video, this includes information on cropping, stretching, alignment, granularity and data rates.

For more information on GetStreamCaps see Exposing Capture and Compression Formats.

Filter developers: Implement this interface on the video output pin when you are writing a video capture or video compression filter. See the comments in axextend.idl for more information.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IAMStreamConfig methodsDescription
SetFormat Sets the audio or video stream's format.
GetFormat Retrieves the audio or video stream's format.
GetNumberOfCapabilities Retrieves the number of stream capabilities structures for the compressor.
GetStreamCaps Obtains audio or video capabilities of a stream depending on which type of structure is pointed to in the pSCC parameter.

IAMStreamConfig::GetFormat

IAMStreamConfig Interface

Retrieves the audio or video stream's format.

Syntax

HRESULT GetFormat(
  AM_MEDIA_TYPE **pmt
  );

Parameters

pmt
[out] Address of a pointer to an AM_MEDIA_TYPE structure.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

When you are done using the media type structure, call the DeleteMediaType function to free the structure.

IAMStreamConfig::GetNumberOfCapabilities

IAMStreamConfig Interface

Retrieves the number of stream capabilities structures for the compressor.

Syntax

HRESULT GetNumberOfCapabilities(
  int *piCount,
  int *piSize
  );

Parameters

piCount
[out] Pointer to the number of VIDEO_STREAM_CONFIG_CAPS and/or AUDIO_STREAM_CONFIG_CAPS structures supported.
piSize
[out] Pointer to the size of the configuration structure (either AUDIO_STREAM_CONFIG_CAPS or VIDEO_STREAM_CONFIG_CAPS).

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

IAMStreamConfig::GetStreamCaps

IAMStreamConfig Interface

Obtains audio, video, or other capabilities of a stream depending on which type of structure is pointed to in the pSCC parameter.

Syntax

HRESULT GetStreamCaps(
  int iIndex,
  AM_MEDIA_TYPE **pmt,
  BYTE *pSCC
  );

Parameters

iIndex
[in] Index to the desired media type and capability pair. Use the GetNumberOfCapabilities method to retrieve the total number of these pairs. Possible index values range from zero to one less than the total number of pairs.
pmt
[out] Address of a pointer to an AM_MEDIA_TYPE structure.
pSCC
[out] Pointer to a stream configuration structure.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

This method enables you to get more information about accepted media types rather than the traditional way of enumerating a pin's media types, so you typically should use it instead of pin enumeration. Information such as possible video capture rates, media types, and sizes is returned by the VIDEO_STREAM_CONFIG_CAPS structure. Audio capabilities of the filter's output pin, including the number of inputs, sampling rate, and bit rate granularity will be returned by an AUDIO_STREAM_CONFIG_CAPS structure.

Call DeleteMediaType to free the pmt media type.

For more information on GetStreamCaps, see Exposing Capture and Compression Formats.

IAMStreamConfig::SetFormat

IAMStreamConfig Interface

Sets the audio or video stream's format.

Syntax

HRESULT SetFormat(
  AM_MEDIA_TYPE *pmt
  );

Parameters

pmt
[in] Pointer to an AM_MEDIA_TYPE structure.

Return Value

Returns an HRESULT value that depends on the implementation of the interface.

Remarks

A call to this method will fail if the pin is streaming.

If your output pin isn't connected and you can connect it with this media type, return S_OK from this method and start enumerating the specified media type as follows: Specify this format as format number zero in the CTransformOutputPin::GetMediaType function's iPosition parameter. You can offer and accept only this type to ensure that the pins will use this format for the connection when it occurs.

If your output pin is already connected and you can provide this type, then reconnect your pin. If the other pin can't accept the media type, fail this call and leave your connection alone.

Passing in NULL as a parameter value can cause some filters to set their default format and forget a previous format you have given it with this method.

The frame rate at which your filter should produce data is determined by the AvgTimePerFrame field of the VIDEOINFOHEADER of the media type your output pin is connected with. You may not be able to capture at any arbitrary frame rate, but only certain rates. If your pin is connected with a media type that asks for a frame rate you can't provide, you should provide frames at the next lowest frame rate possible. For instance, if your media type has AvgTimePerFrame=333333 (approximately 1/30 of a second, meaning 30 frames per second), and you can only capture 29.97 or 35 frames per second, you should provide frames at 29.97 frames per second, since that is the closest value lower than 30 that you can provide. You can provide a higher frame rate than asked if the frame rate you provide does not create frame durations more than 1 microsecond shorter than requested, since the AvgTimePerFrame may simply have rounding errors. If the AvgTimePerFrame field is 0, you can supply frames at any default frame rate that you want.