CMediaType Class

CMediaType class hierarchy

When filters are connected, they typically negotiate a type between them. This type describes the format of the data to be exchanged; if the filters do not agree on a media type, they cannot connect. Microsoft® DirectShow® describes types through the media type structure, which contains two conceptual parts. The first is a list of members that describes generic attributes of a data stream. An example of this is a member that declares whether the data will be passed in fixed-size buffers. The second part of the structure is a variable-length block of data. How large the block of data should be and what it will contain depend on the type of data stream. For example, if the data stream is digital video, the format block is a VIDEOINFOHEADER structure. If, on the other hand, it is digital audio, the format block is a Microsoft Win32® WAVEFORMATEX structure.

A data stream type (for example, digital video) is set with a combination of two globally unique identifiers (GUIDs), called a major type and a subtype. The major type describes the overall class of data, examples of which might be digital video, digital audio, MIDI, or text captions. The subtype should supply a more specific description of the data type. In the case of digital video, for example, the subtype could be RGB8, RGB16, or RGB32 (among others). By having these two types in a generic structure (AM_MEDIA_TYPE), a component, such as a filter graph, can connect filters without any knowledge that is type specific.

The distinction between what goes in the major type and the subtype is somewhat arbitrary. However, as a general rule, transformations between major types (for example, video to audio or video to MIDI) should be relatively rare. Such a rare exception might be a transformation between audio and MIDI. As for the subtype, the more information promoted from the type-specific format block into the subtype, the better the design.

As an example of promoting type-specific information to the subtype, video in DirectShow uses a VIDEOINFOHEADER structure for the type-specific format block. This contains a Win32 BITMAPINFOHEADER structure that defines the video stream. BITMAPINFOHEADER contains the bit depth of the video, such as 8-bit, 16-bit, or 24-bit. This information is duplicated in the subtype field, because a subtype of RGB8 directly infers a bit count of 8.

DirectShow defines a number of major types. The most important of these are a video type that uses VIDEOINFOHEADER for the variable-length format block, and an audio that uses WAVEFORMATEX. However, it is insufficient to have a major type (such as digital video) inferring the contents of the format block (in this case, VIDEOINFOHEADER). The principal reason for this is extensibility: the format block type must be able to be updated without changing the less-specific major type. Therefore, what the format block actually contains is inferred by another GUID called the format type. If the format block contains VIDEOINFOHEADER, the format type GUID will be FORMAT_VideoInfo.

The principal use of the CMediaType class is to manage a media type structure in a simple way. At the same time, the class provides some extra helper functions (such as format-block copying and allocation). The class can be cast to an AM_MEDIA_TYPE structure when an interface method requires one to be passed to it.

The CMediaType class contains a pointer to a block of memory. When copying a CMediaType object, it is insufficient to simply copy the pointer. In C++, a data copy is required, which actually allocates a new block of memory and copies the data into it. This is the purpose of the copy operator.

Similarly, when comparing two CMediaType objects, you must compare the blocks of variable-length data (actually using memcmp) when producing the final result. To make this possible, CMediaType overrides the equivalence operator.

Member Functions

AllocFormatBuffer Allocates an uninitialized format block in the object.
CMediaType Constructs a CMediaType object.
Format Retrieves the format block for this media type.
FormatLength Retrieves the length of the format block of this object.
FormatType Retrieves a pointer to the format type.
GetSampleSize Retrieves the size of the samples.
InitMediaType Initializes the media type.
IsFixedSize Queries whether the samples are fixed in length.
IsPartiallySpecified Checks if the media type is not completely specified.
IsTemporalCompressed Queries whether the data stream is compressed temporally.
IsValid Queries whether the media type is currently valid.
MatchesPartial Checks whether this media type matches another media type that is only partially specified.
ReallocFormatBuffer Reallocates the format block, maintaining its current content where possible.
ResetFormatBuffer Deletes any format block that is currently present.
SetFormat Sets the format block.
SetFormatType Sets the type of the format block in the object.
SetSampleSize Sets the size of the samples.
SetSubtype Sets the subtype.
SetTemporalCompression Marks the media type to indicate whether the data stream it describes contains temporal compression.
SetType Sets the major type.
SetVariableSize Marks the media type to indicate that samples will vary in length.
Subtype Retrieves a pointer to the subtype.
Type Retrieves a pointer to the major type.

Operators

operator = Performs a copy operation.
operator == Tests for equality between CMediaType objects.
operator != Tests for inequality between CMediaType objects.

CMediaType::AllocFormatBuffer

CMediaType Class

Allocates a block of memory for the format block.

Syntax

BYTE* AllocFormatBuffer(
    ULONG length
);

Parameters

length
Size required for the format block.

Return Value

Returns a pointer to the new block if successful; otherwise, returns NULL.

Remarks

Any previous format block is deleted and a new block is allocated and installed. The size required must be nonzero.

CMediaType::CMediaType

CMediaType Class

Constructs a CMediaType object.

Syntax

CMediaType(void);
CMediaType(
    const GUID *majortype
);
CMediaType(
    const AM_MEDIA_TYPE& mtype
);
CMediaType(
    const CMediaType& cmtype
);

Parameters

majortype
Pointer to a major type GUID.
mtype
AM_MEDIA_TYPE structure.
cmtype
CMediaType object from which this object is constructed.

Return Value

No return value.

Remarks

A CMediaType object can be constructed in a number of different ways. The class provides a default constructor that takes no parameters. It can also be constructed based on an AM_MEDIA_TYPE structure or another CMediaType object. In both cases, it takes a data copy of the format block before returning.

CMediaType::Format

CMediaType Class

Retrieves a pointer to the variable-length format block of the object.

Syntax

BYTE* Format(void) const;

Return Value

Returns the format block of the object whose content is type-specific.

Remarks

If no format block has been allocated, it might return NULL.

CMediaType::FormatLength

CMediaType Class

Retrieves the size, in bytes, of the format block that the object contains.

Syntax

ULONG FormatLength(void) const;

Return Value

Returns the length of the format block, or NULL if no format block is present.

CMediaType::FormatType

CMediaType Class

Retrieves the format type.

Syntax

const GUID *FormatType(void) const;

Return Value

Returns a pointer to the format type.

Remarks

The format GUID describes the content of the variable-length format block. Examples of format types are FORMAT_VideoInfo and FORMAT_WaveFormatEx.

CMediaType::GetSampleSize

CMediaType Class

Retrieves the maximum sample size for the data stream.

Syntax

ULONG GetSampleSize(void) const;

Return Value

Returns the maximum size of any sample to be sent, or zero to indicate that the sample size is variable.

CMediaType::InitMediaType

CMediaType Class

Initializes the sample.

Syntax

void InitMediaType(void);

Return Value

No return value.

Remarks

This member function clears memory, sets the fixed sample size property, and sets the sample size to 1.

CMediaType::IsFixedSize

CMediaType Class

Determines if the samples for the stream will be fixed or variable size.

Syntax

BOOL IsFixedSize(void) const;

Return Value

Returns one of the following values.
TRUE Samples will be fixed size.
FALSE Samples will be variable length.

CMediaType::IsPartiallySpecified

CMediaType Class

Determines if the media type is only partially defined. This is the case if the major type or format type is GUID_NULL.

Syntax

BOOL IsPartiallySpecified(void) const;

Return Value

Returns one of the following values.
TRUE Media type is partially specified.
FALSE Media type is completely specified.

Remarks

This function does not check the subtype.

CMediaType::IsTemporalCompressed

CMediaType Class

Determines if the stream will be compressed temporally.

Syntax

BOOL IsTemporalCompressed(void) const;

Return Value

Returns one of the following values.
TRUE Stream will have temporal compression.
FALSE Stream will have no temporal compression.

Remarks

Some data streams, such as compressed video, have temporal dependencies between successive samples. Other data streams do not have temporal dependencies between their samples; that is, each sample can be treated as an independent unit; for example, MIDI.

CMediaType::IsValid

CMediaType Class

Determines whether the object has a valid major type.

Syntax

BOOL IsValid(void) const;

Return Value

Returns one of the following values.
TRUE CMediaType object has a valid major type.
FALSE CMediaType object does not have a valid major type.

Remarks

When CMediaType objects are constructed, their GUIDs are initialized with GUID_NULL (unless they are constructed based on another AM_MEDIA_TYPE structure or CMediaType object). This member function is useful for discovering if the object has been correctly initialized.

CMediaType::MatchesPartial

CMediaType Class

Determines if this media type matches the media type pointed to by the ppartial parameter.

Syntax

BOOL MatchesPartial(
    const CMediaType *ppartial
    ) const;

Parameters

ppartial
Pointer to the media type to match.

Return Value

Returns one of the following values.
TRUE Media types match for the parts that are defined.
FALSE Media types do not match.

Remarks

The matching applies only for the parts of ppartial that are defined. That is, this only matches the major type, subtype, or format type of the media type if these are not defined as GUID_NULL.

CMediaType::ReallocFormatBuffer

CMediaType Class

Reallocates the format block to a new size.

Syntax

BYTE* ReallocFormatBuffer(
    ULONG length
);

Parameters

length
New size required for the format block.

Return Value

Returns a pointer to the new block if successful; otherwise, returns NULL.

Remarks

Any current format block will be copied into the newly allocated block up to its maximum size. Any excess will be lost when the new block is smaller than the old one. When the new block is larger, the excess is not filled with zeros.
The size required must be nonzero.

CMediaType::ResetFormatBuffer

CMediaType Class

Deletes any format block currently held, sets it to NULL, and sets the size of the format block to zero.

Syntax

void ResetFormatBuffer(void);

Return Value

No return value.

CMediaType::SetFormat

CMediaType Class

Sets the variable-length format block.

Syntax

BOOL SetFormat(
    BYTE *pFormat,
    ULONG length
);

Parameters

pFormat
Pointer to a block of memory containing type-specific information.
length
Overall length of the format block.

Return Value

Returns one of the following values.
TRUE Format block was set.
FALSE An error occurred; most likely there was no memory available.

Remarks

The function takes a copy of the format block and stores that internally.

CMediaType::SetFormatType

CMediaType Class

Sets the GUID that describes the content of the format block.

Syntax

void SetFormatType(
    const GUID *pformattype
);

Parameters

pformattype
Pointer to a GUID describing the format type.

Return Value

No return value.

Remarks

The format GUID describes what can be expected to be found in the variable-length format block. For example, if the format type is FORMAT_VideoInfo, the format block should contain a VIDEOINFOHEADER structure. The creator of this object is responsible for making them consistent.

CMediaType::SetSampleSize

CMediaType Class

Sets the maximum sample size for the data stream.

Syntax

void SetSampleSize(
    ULONG sz
);

Parameters

sz
Size of the sample.

Return Value

No return value.

Remarks

If the sample size passed is zero, the object is set so that the data stream will send variable-length samples (the CMediaType::GetSampleSize member function will return zero). Otherwise, it will set the maximum size of the sample to the size specified in the sz parameter.

CMediaType::SetSubtype

CMediaType Class

Sets the subtype for the object.

Syntax

void SetSubtype(
    const GUID *psubtype
);

Parameters

psubtype
Pointer to a GUID defining the subtype for the object.

Return Value

No return value.

CMediaType::SetTemporalCompression

CMediaType Class

Marks the media type to indicate whether the data stream it describes contains temporal compression.

Syntax

void SetTemporalCompression(
    BOOL bCompressed
);

Parameters

bCompressed
Value specifying whether the stream will contain temporal compression; set to TRUE to indicate that it will, or FALSE otherwise.

Return Value

No return value.

CMediaType::SetType

CMediaType Class

Sets the major type for the object.

Syntax

void SetType(
    const GUID *ptype
);

Parameters

ptype
Pointer to a GUID defining the major type for the object.

Return Value

No return value.

CMediaType::SetVariableSize

CMediaType Class

Sets the media type to indicate that the data stream will send variable-length samples.

Syntax

void SetVariableSize(void);

Return Value

No return value.

Remarks

Subsequent calls to CMediaType::GetSampleSize will return zero.

CMediaType::Subtype

CMediaType Class

Retrieves the subtype.

Syntax

const GUID *Type(void) const;

Return Value

Returns a pointer to the subtype.

Remarks

The subtype GUID gives finer detail within the major type of data represented by this media type.

CMediaType::Type

CMediaType Class

Retrieves the major type.

Syntax

const GUID *Type(void) const;

Return Value

Returns a pointer to the major type.

Remarks

The major type GUID describes the class of data represented by this media type.

CMediaType::operator =

CMediaType Class

Performs a copy operation.

The CMediaType variation of this operator is the copy constructor for a CMediaType object.

The AM_MEDIA_TYPE variation of this operator is the copy constructor for an AM_MEDIA_TYPE object.

Syntax

CMediaType& operator=(
    const CMediaType& rt
);
CMediaType& operator=(
    const AM_MEDIA_TYPE& mrt
);

Parameters

rt
Object to copy during the assignment operation.
mrt
Object to copy during the assignment operation.

Return Value

Returns a reference to this object after the operation.

Remarks

Because the CMediaType class inherits publicly from AM_MEDIA_TYPE, the compiler could generate the copy constructor for the AM_MEDIA_TYPE object itself. However, this could introduce some memory conflicts and leaks in the process because the structure contains a dynamically allocated block (which the AM_MEDIA_TYPE pbFormat member points to), which the compiler's copy constructor will not copy correctly.

CMediaType::operator ==

CMediaType Class

Tests for equality between CMediaType objects.

Syntax

inline BOOL operator==(
    const CMediaType& rt
    ) const;

Parameters

rt
CMediaType object corresponding to the right side of the operator.

Return Value

Returns TRUE if the CMediaType object tested is equal to this object; otherwise, returns FALSE.

Remarks

This object is on the left side of the operator.

CMediaType::operator !=

CMediaType Class

Tests for inequality between CMediaType objects.

Syntax

BOOL operator!=(
    const CMediaType& rt
    ) const;

Parameters

rt
CMediaType object corresponding to the right side of the operator.

Return Value

Returns TRUE if the CMediaType object tested is not equal to this object; otherwise, returns FALSE.

Remarks

This object is on the left side of the operator.

AllocFormatBuffer	Allocates an uninitialized format block in the object.
CMediaType	Constructs a CMediaType object.
Format	Retrieves the format block for this media type.
FormatLength	Retrieves the length of the format block of this object.
FormatType	Retrieves a pointer to the format type.
GetSampleSize	Retrieves the size of the samples.
InitMediaType	Initializes the media type.
IsFixedSize	Queries whether the samples are fixed in length.
IsPartiallySpecified	Checks if the media type is not completely specified.
IsTemporalCompressed	Queries whether the data stream is compressed temporally.
IsValid	Queries whether the media type is currently valid.
MatchesPartial	Checks whether this media type matches another media type that is only partially specified.
ReallocFormatBuffer	Reallocates the format block, maintaining its current content where possible.
ResetFormatBuffer	Deletes any format block that is currently present.
SetFormat	Sets the format block.
SetFormatType	Sets the type of the format block in the object.
SetSampleSize	Sets the size of the samples.
SetSubtype	Sets the subtype.
SetTemporalCompression	Marks the media type to indicate whether the data stream it describes contains temporal compression.
SetType	Sets the major type.
SetVariableSize	Marks the media type to indicate that samples will vary in length.
Subtype	Retrieves a pointer to the subtype.
Type	Retrieves a pointer to the major type.

operator =	Performs a copy operation.
operator ==	Tests for equality between CMediaType objects.
operator !=	Tests for inequality between CMediaType objects.

TRUE	Samples will be fixed size.
FALSE	Samples will be variable length.

TRUE	Media type is partially specified.
FALSE	Media type is completely specified.

TRUE	Stream will have temporal compression.
FALSE	Stream will have no temporal compression.

TRUE	CMediaType object has a valid major type.
FALSE	CMediaType object does not have a valid major type.

TRUE	Media types match for the parts that are defined.
FALSE	Media types do not match.

TRUE	Format block was set.
FALSE	An error occurred; most likely there was no memory available.