ISampleGrabber::SetMediaType method
[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.]
Note
[Deprecated. This API may be removed from future releases of Windows.]
The SetMediaType method specifies the media type for the connection on the input pin of the Sample Grabber.
Syntax
HRESULT SetMediaType(
const AM_MEDIA_TYPE *pType
);
Parameters
-
pType
-
Pointer to an AM_MEDIA_TYPE structure specifies the required media type. It is not necessary to set all the structure members; see Remarks for details.
Return value
Returns S_OK.
Remarks
By default, the Sample Grabber has no preferred media type. To ensure that the Sample Grabber connects to the correct filter, call this method before building the filter graph.
This method restricts the range of media types that the filter will accept. When the filter connects, it tries to match the media type given in pType. To do so, it compares the major type, subtype, and format type GUIDs, in that order. For each of these GUIDs, if pType has the value GUID_NULL, the Sample Grabber accepts the media type without any further checks. If pType has any other value, the Sample Grabber compares it to the GUID in the connection type. Unless the two GUIDs match exactly, the Sample Grabber rejects the connection.
For video media types, the Sample Grabber ignores the format block. Therefore, it will accept any video size and frame rate. When you call SetMediaType, set the format block (pbFormat) to NULL and the size (cbFormat) to zero. For audio media types, the Sample Grabber will examine the WAVEFORMATEX structure and will require the other filter to connect with that format — unless the format block in pType is NULL, or the format tag is WAVE_FORMAT_PCM and the other structure members are zero.
Example 1:
- Major type: MEDIATYPE_Video
- Subtype: GUID_NULL
- Format type: GUID_NULL
The Sample Grabber will accept any video type where the major type equals MEDIATYPE_Video. It will not check the subtype.
Example 2:
- Major type: MEDIATYPE_Video
- Subtype: MEDIASUBTYPE_RGB24
- Format type: GUID_NULL
Now the Sample Grabber will check the subtype, and accept only RGB 24 video.
Limitations: Regardless of what type you set, the Sample Grabber Filter rejects any video types with top-down orientation (negative biHeight), or with a format type of FORMAT_VideoInfo2. In this case, although the SetMediaType method succeeds, the filter will not connect.
Note
The header file Qedit.h is not compatible with Direct3D headers later than version 7.
Note
To obtain Qedit.h, download the Microsoft Windows SDK Update for Windows Vista and .NET Framework 3.0. Qedit.h is not available in the Microsoft Windows SDK for Windows 7 and .NET Framework 3.5 Service Pack 1.
Requirements
| Requirement | Value |
|---|---|
| Header |
|
| Library |
|
See also