IAMStreamConfig::GetStreamCaps

The GetStreamCaps method retrieves a set of format capabilities.

Syntax

HRESULT GetStreamCaps(
  int iIndex,
  AM_MEDIA_TYPE **pmt,
  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. For audio, use the AUDIO_STREAM_CONFIG_CAPS structure. To determine the required size of the array, call the GetNumberOfCapabilities method.

Return Values

Returns an HRESULT value. Possible values include the following.

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.

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.

Example Code

The following example retrieves the first supported format (index zero) on a video output pin. Then it configures the pin to use the smallest output size for that format. To do so, it modifies the format block's BITMAPINFOHEADER structure with the new width and height; and sets the lSampleSize member of the AM_MEDIA_TYPE structure to the new sample size. The sample size depends partly on the bit depth, which can be determined from the media subtype. (For brevity, this example shows only the case for UYVY format. Also, it assumes that the caller already knows the pin produces video output.)

int iCount, iSize;
VIDEO_STREAM_CONFIG_CAPS scc;
AM_MEDIA_TYPE *pmt;

hr = pConfig->GetNumberOfCapabilities(&iCount, &iSize);
if (sizeof(scc) != iSize)
{
    // This is not the structure we were expecting.
    return E_FAIL;
}
// Get the first format.
hr = pConfig->GetStreamCaps(0, &pmt, reinterpret_cast<BYTE*>(&scc));
if (hr == S_OK)
{
    // Is it VIDEOINFOHEADER and UYVY?
    if (pmt->formattype == FORMAT_VideoInfo && 
        pmt->subtype == MEDIASUBTYPE_UYVY)
    {
        // Find the smallest output size.
        LONG width = scc.MinOutputSize.cx;
        LONG height = scc.MinOutputSize.cy;
        LONG cbPixel = 2;  // Bytes per pixel in UYVY
        
        // Modify the format block.
        VIDEOINFOHEADER *pVih = 
            reinterpret_cast<VIDEOINFOHEADER*>(pmt->pbFormat);
        pVih->bmiHeader.biWidth = width;
        pVih->bmiHeader.biHeight = height;

        // Set the sample size and image size.
        // (Round the image width up to a DWORD boundary.)
        pmt->lSampleSize = pVih->bmiHeader.biSizeImage = 
            ((width + 3) & ~3) * height * cbPixel; 
       
        // Now set the format.
        hr = pConfig->SetFormat(pmt);
        if (FAILED(hr))
        {
            MessageBox(NULL, TEXT("SetFormat Failed\n"), NULL, MB_OK);
        }
        DeleteMediaType(pmt);
    }
}

See Also

• Error and Success Codes
• IAMStreamConfig Interface