IAMStreamConfig::GetStreamCaps method

The GetStreamCaps method retrieves a set of format capabilities.

Syntax


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

Parameters

iIndex [in]

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

pmt [out]

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

pSCC [out]

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 codeDescription
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.



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

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Strmif.h (include Dshow.h)

Library

Strmiids.lib

See also

Error and Success Codes
IAMStreamConfig Interface

 

 

Community Additions

ADD
Show:
© 2014 Microsoft