IAMStreamConfig::GetStreamCaps method (strmif.h)

Article
07/27/2023

[The feature associated with this page, DirectShow, is a legacy feature. It has been superseded by MediaPlayer, IMFMediaEngine, and Audio/Video Capture in Media Foundation. Those features have been optimized for Windows 10 and Windows 11. Microsoft strongly recommends that new code use MediaPlayer, IMFMediaEngine and Audio/Video Capture in Media Foundation instead of DirectShow, when possible. Microsoft suggests that existing code that uses the legacy APIs be rewritten to use the new APIs if possible.]

The GetStreamCaps method retrieves a set of format capabilities.

Syntax

HRESULT GetStreamCaps(
  [in]  int           iIndex,
  [out] AM_MEDIA_TYPE **ppmt,
  [out] BYTE          *pSCC
);

Parameters

[in] iIndex

Specifies the format capability to retrieve, indexed from zero. To determine the number of capabilities that the pin supports, call the IAMStreamConfig::GetNumberOfCapabilities method.

[out] ppmt

Address of a pointer to an AM_MEDIA_TYPE structure. The method allocates the structure and fills it with a media type.

[out] pSCC

Pointer to a byte array allocated by the caller. For video, use the VIDEO_STREAM_CONFIG_CAPS structure (see Remarks). For audio, use the AUDIO_STREAM_CONFIG_CAPS structure. To determine the required size of the array, call the GetNumberOfCapabilities method. The size is returned in the piSize parameter.

Return value

Returns an HRESULT value. Possible values include the following.

Return code	Description
S_FALSE	Specified index is too high.
S_OK	Success.
E_INVALIDARG	Invalid index.
E_OUTOFMEMORY	Insufficient memory.
E_POINTER	NULL pointer value.
VFW_E_NOT_CONNECTED	The input pin is not connected.

Remarks

This method returns two pieces of information:

The pmt parameter receives a filled-in AM_MEDIA_TYPE structure, which describes one supported output format.
The pSCC parameter receives a structure that contains additional format information. For video, pSCC receives a VIDEO_STREAM_CONFIG_CAPS structure. For audio, it receives an AUDIO_STREAM_CONFIG_CAPS structure.

Note Use of the VIDEO_STREAM_CONFIG_CAPS structure to configure a video device is deprecated. Although the caller must allocate the buffer, it should ignore the contents after the method returns. The capture device will return its supported formats through the pmt parameter.

To configure the output pin so that it uses this format, call the IAMStreamConfig::SetFormat method and pass in the value of pmt.

Before calling SetFormat, you can modify the AM_MEDIA_TYPE structure in pmt, using the information in pSCC. For example, an audio pin might return a default media type of 44-kHz, 16-bit stereo in the pmt parameter. Based on the values returned in the AUDIO_STREAM_CONFIG_CAPS structure, you might change this format to 8-bit mono before calling SetFormat.

The method allocates the memory for the AM_MEDIA_TYPE structure that is returned in the pmt parameter. The caller must release the memory, including the format block. You can use the DeleteMediaType helper function in the base class library. The caller must allocate the memory for the pSCC parameter.

On some compression filters, this method fails if the filter's input pin is not connected.

Filter Developers: For more information on implementing this method, see Exposing Capture and Compression Formats.

Examples

The following example retrieves the first supported format (index zero) on a video output pin and then sets this format on the pin.

C++
int iCount, iSize; BYTE pSCC = NULL; AM_MEDIA_TYPE pmt; hr = pConfig->GetNumberOfCapabilities(&iCount, &iSize); pSCC = new BYTE[iSize]; if (pSCC == NULL) { // TODO: Out of memory error. } // Get the first format. hr = pConfig->GetStreamCaps(0, &pmt, pSCC)); if (hr == S_OK) { // TODO: Examine the format. If it's not suitable for some // reason, call GetStreamCaps with the next index value (up // to iCount). Otherwise, set the format: hr = pConfig->SetFormat(pmt); if (FAILED(hr)) { // TODO: Error handling. } DeleteMediaType(pmt); } delete [] pSCC;

C++

int iCount, iSize;
BYTE *pSCC = NULL;
AM_MEDIA_TYPE *pmt;
hr = pConfig->GetNumberOfCapabilities(&iCount, &iSize);
pSCC = new BYTE[iSize];
if (pSCC == NULL)
{
// TODO: Out of memory error.
}
// Get the first format.
hr = pConfig->GetStreamCaps(0, &pmt, pSCC));
if (hr == S_OK)
{
// TODO: Examine the format. If it's not suitable for some
// reason, call GetStreamCaps with the next index value (up
// to iCount). Otherwise, set the format:
hr = pConfig->SetFormat(pmt);
if (FAILED(hr))
{
// TODO: Error handling.
}
DeleteMediaType(pmt);
}
delete [] pSCC;

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	strmif.h (include Dshow.h)
Library	Strmiids.lib