IAMStreamConfig Interface

The IAMStreamConfig interface enables you to find out what types of formats an output pin can be connected with. Additionally it can be used to set stream formats, to tell a pin to connect with a certain format the next time it's connected, or to make it reconnect with a new format if it's already connected. Audio/video capture and audio/video compression filters implement this interface on their output pins, but potentially any filter dealing with audio or video can implement this interface on its output pins.

Use this interface to set a pin's output format, rather than connecting the pin by using a specific media type. After setting an output format, the pin will try to use that format the next time it connects. This enables you to call the IGraphBuilder::Render method on that pin and get a desired format without connecting the pins and providing a CMediaType class object. Your pin should offer only the media type set in the CMediaType::SetFormat function in its enumeration of media types after SetFormat is called. Before then, offer media types as usual. This will ensure that the pin uses that format for connection. An application that needs to enumerate accepted media types using CBasePin::GetMediaType must do so before calling SetFormat.

The IAMStreamConfig::GetStreamCaps method can get more information about accepted media types than the traditional way of enumerating a pin's media types, so you typically should use it instead of pin enumeration. GetStreamCaps retrieves information about the kinds of audio and video formats allowed.

GetStreamCaps provides detailed information about the media types and capabilities supported by this pin. This method returns a set of structures that includes pairs of AM_MEDIA_TYPE and either a VIDEO_STREAM_CONFIG_CAPS or an AUDIO_STREAM_CONFIG_CAPS structures describing an accepted media type and how that media type can be altered to create other acceptable media types.

Note The cropping rectangle described throughout the IAMStreamConfig documentation is the same as the VIDEOINFOHEADER structure's rcSource rectangle for the output pin.

The output rectangle described throughout the IAMStreamConfig documentation is the same as the width and height members of the output pin's BITMAPINFOHEADER structure.

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

Implement this interface on the video output pin when you are writing a video capture or video compression filter.

Use this interface when your application or filter must get or set audio or video stream information.

WDM capture applications that need to preview and then capture might have to set audio and video stream information on the preview pin and again on the capture pin.

Methods in Vtable Order

IUnknown methods Description
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

IAMStreamConfig methods Description

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.

IUnknown methods	Description
QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.
IAMStreamConfig methods	Description
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

Be sure to initialize the media type structure before using it. For example, the following code fragment calls the Win32® ZeroMemory function to initialize the structure.
AM_MEDIA_TYPE pmt;
if (SUCCEEDED(GetFormat(&pmt))) ...
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 (approx 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.