Microsoft DirectX 8.0

CMediaSample Class

CMediaSample class hierarchy

Defines a media sample that supports the IMediaSample2 interface. The media sample contains a pointer to a memory buffer, and various properties stored as protected member variables.

Declaration: Amfilter.h

Media samples are created by allocators, which are derived from the CBaseAllocator class. The CMediaSample constructor receives a pointer to an allocated buffer, along with the size of the buffer. Other properties are typically set and retrieved through IMediaSample interface methods.

The life cycle of a media sample differs from that of most COM objects:

Protected Member Variables
m_dwFlagsSample property flags.
m_dwTypeSpecificFlagsType-specific flags.
m_pBufferPointer to the memory buffer that contains the media data.
m_lActualLength of the valid data in the buffer, in bytes.
m_cbBufferSize of the buffer, in bytes.
m_pAllocatorPointer to the allocator that created this sample.
m_pNextPointer to the next sample in the allocator's list of samples.
m_Start Sample start time.
m_End Sample end time.
m_MediaStartMedia start time.
m_MediaEndMedia stop time.
m_pMediaTypePointer to the media type, if the type has changed from the previous sample in the data stream.
m_dwStreamIdStream identifier.
Public Member Variables
m_cRefReference count.
Public Methods
CMediaSampleConstructor method.
~CMediaSampleDestructor method. Virtual.
SetPointerSets the pointer to the memory buffer.
IMediaSample Methods
GetPointerRetrieves a read/write pointer to the buffer.
GetSizeRetrieves the size of the buffer.
GetTimeRetrieves the stream times at which this sample should begin and finish.
SetTimeSets the stream times at which this sample should start and finish.
IsSyncPointDetermines if the beginning of the sample is a synchronization point.
SetSyncPointSpecifies whether the beginning of this sample is a synchronization point.
IsPrerollDetermines if this sample is a preroll sample.
SetPrerollSpecifies whether this sample is a preroll sample.
GetActualDataLengthRetrieves the length of the valid data in the buffer.
SetActualDataLengthSets the length of the valid data in the buffer.
GetMediaTypeRetrieves the media type, if the media type differs from the previous sample.
SetMediaTypeSets the media type for the sample.
IsDiscontinuityDetermines if this sample represents a break in the data stream.
SetDiscontinuitySpecifies whether this sample represents a break in the data stream.
GetMediaTimeRetrieves the media times for this sample.
SetMediaTimeSets the media times for this sample.
IMediaSample2 Methods
GetPropertiesRetrieves the properties of the sample.
SetPropertiesSets the properties of the sample.

CMediaSample.m_dwFlags

CMediaSample Class

Sample property flags. Bitwise combination of flags from the AM_SAMPLE_PROPERTY_FLAGS enumerated type.

Syntax

DWORD m_dwFlags;

CMediaSample.m_dwTypeSpecificFlags

CMediaSample Class

Type-specific flags. The meaning of this member variable depends on the media type of the sample.

Syntax

DWORD m_dwTypeSpecificFlags;

CMediaSample.m_pBuffer

CMediaSample Class

Pointer to the memory buffer that contains the media data.

Syntax

LPBYTE m_pBuffer;

CMediaSample.m_lActual

CMediaSample Class

Length of the valid data in the buffer, in bytes. The value must be equal to or less than the size of the buffer (m_cbBuffer).

Syntax

LONG m_lActual;

CMediaSample.m_cbBuffer

CMediaSample Class

Size of the buffer, in bytes.

Syntax

LONG m_cbBuffer;

CMediaSample.m_pAllocator

CMediaSample Class

Pointer to the allocator that created this sample.

Syntax

CBaseAllocator *m_pAllocator;

Remarks

Although the sample keeps a pointer to the allocator, it does not hold a reference count. Instead, the allocator increments its own reference count in the IMemAllocator::GetBuffer method, and releases itself in the IMemAllocator::ReleaseBuffer method. This guarantees that the allocator will be available as long as another object is using the sample.

CMediaSample.m_pNext

CMediaSample Class

Pointer to the next sample in the allocator's list of samples.

Syntax

CMediaSample *m_pNext;

CMediaSample.m_Start

CMediaSample Class

Sample start time. This value is valid only if the m_dwFlags member variable contains the AM_SAMPLE_TIMEVALID flag.

Syntax

REFERENCE_TIME m_Start;

CMediaSample.m_End

CMediaSample Class

Sample end time. This value is valid only if the m_dwFlags member variable contains the AM_SAMPLE_STOPVALID flag.

Syntax

REFERENCE_TIME m_End;

CMediaSample.m_MediaStart

CMediaSample Class

Media start time.

Syntax

LONGLONG m_MediaStart;

CMediaSample.m_MediaEnd

CMediaSample Class

Media stop time. This value is calculated as an offset from the media start time (m_MediaStart).

Syntax

LONG m_MediaEnd;

CMediaSample.m_pMediaType

CMediaSample Class

Pointer to the media type, if the type has changed from the previous sample in the data stream. Otherwise, this member variable is NULL.

Syntax

AM_MEDIA_TYPE *m_pMediaType;

CMediaSample.m_dwStreamId

CMediaSample Class

Stream identifier. For more information, see AM_SAMPLE2_PROPERTIES.

Syntax

DWORD m_dwStreamId;

CMediaSample.m_cRef

CMediaSample Class

Reference count.

Syntax

LONG m_cRef;

CMediaSample::CMediaSample

CMediaSample Class

Constructor method.

Syntax

CMediaSample(
    TCHAR *pName,
    CBaseAllocator *pAllocator,
    HRESULT *phr,
    LPBYTE pBuffer = NULL,
    LONG length = 0
); 

Parameters

pName
Pointer to a string containing the name of the media sample.
pAllocator
Pointer to the CBaseAllocator object that created this sample.
phr
Pointer to a variable that receives an HRESULT value indicating the success or failure of the method.
pBuffer
Pointer to a memory buffer allocated by the caller, of size length.
length
Length of the memory buffer.

Remarks

The base class does not modify the HRESULT value passed in the phr parameter.

CMediaSample::~CMediaSample

CMediaSample Class

Destructor method.

Syntax

~CMediaSample(void);

CMediaSample::GetActualDataLength

CMediaSample Class

Retrieves the length of the valid data in the buffer. Implements the IMediaSample::GetActualDataLength method.

Syntax

LONG GetActualDataLength(void);

Return Value

Returns the length of the valid data, in bytes.

Remarks

The m_lActual member variable specifies this property.

CMediaSample::GetMediaTime

CMediaSample Class

Retrieves the media times for this sample. Implements the IMediaSample::GetMediaTime method.

Syntax

HRESULT GetMediaTime(
    LONGLONG *pStart,
    LONGLONG *pEnd
);

Parameters

pStart
Pointer to a variable that receives the media start time.
pEnd
Pointer to a variable that receives the media stop time.

Return Value

Returns one of the HRESULT values shown in the following table.

S_OKSuccess.
VFW_E_MEDIA_TIME_NOT_SETNo media times were set for this sample.

Remarks

The m_MediaEnd member variable specifies an offset from m_MediaStart, but the value received by the pEnd parameter is an absolute media time, calculated as m_MediaStart + m_MediaEnd.

For information about media times, see Time and Clocks in DirectShow.

CMediaSample::GetMediaType

CMediaSample Class

Retrieves the media type, if the media type differs from the previous sample. Implements the IMediaSample::GetMediaType method.

Syntax

HRESULT GetMediaType(
    AM_MEDIA_TYPE **ppMediaType
);

Parameters

ppMediaType
Address of a variable that receives a pointer to an AM_MEDIA_TYPE structure. If the media type has not changed from the previous sample, *ppMediaType is set to NULL.

Return Value

Returns one of the HRESULT values shown in the following table.

S_FALSEThe media type has not changed from the previous sample.
S_OKSuccess.
E_OUTOFMEMORYInsufficient memory.

Remarks

When you are done with the media type, free the memory block by calling the DeleteMediaType utility function.

The m_pMediaType member variable specifies the media type. The m_dwFlags member variable specifies whether the media type has changed.

CMediaSample::GetPointer

CMediaSample Class

Retrieves a read/write pointer to the buffer. Implements the IMediaSample::GetPointer method.

Syntax

HRESULT GetPointer(
    BYTE **ppBuffer
);

Parameters

ppBuffer
Address of a variable that receives a pointer to the buffer.

Return Value

Returns S_OK.

CMediaSample::GetProperties

CMediaSample Class

Retrieves the properties of the sample. Implements the IMediaSample2::GetProperties method.

Syntax

HRESULT GetProperties(
    DWORD cbProperties,
    BYTE *pbProperties
);

Parameters

cbProperties
Length of property data to retrieve, in bytes.
pbProperties
Pointer to a buffer of size cbProperties.

Return Value

Returns one of the HRESULT values shown in the following table.

S_OKSuccess.
E_POINTERNULL pointer argument.

CMediaSample::GetSize

CMediaSample Class

Retrieves the size of the buffer. Implements the IMediaSample::GetSize method.

Syntax

LONG GetSize(void);

Return Value

Returns the size of the buffer, in bytes.

CMediaSample::GetTime

CMediaSample Class

Retrieves the stream times at which this sample should begin and finish. Implements the IMediaSample::GetTime method.

Syntax

HRESULT GetTime(
    REFERENCE_TIME *pTimeStart,
    REFERENCE_TIME *pTimeEnd
);

Parameters

pTimeStart
Pointer to a variable that receives the beginning stream time, in 100-nanosecond units.
pTimeEnd
Pointer to a variable that receives the ending stream time, in 100-nanosecond units. If the sample has no stop time, the value is set to the start time plus one.

Return Value

Returns one of the HRESULT values shown in the following table.

S_OKSuccess.
VFW_S_NO_STOP_TIMESample has a valid start time, but no stop time.
VFW_E_SAMPLE_TIME_NOT_SETSample does not have valid time stamps.

Remarks

The m_Start and m_End member variables specify the time stamps. The m_dwFlags member variable specifies whether the time stamps are valid.

For information about time stamps, see Time and Clocks in DirectShow.

CMediaSample::IsDiscontinuity

CMediaSample Class

Determines if this sample represents a break in the data stream. Implements the IMediaSample::IsDiscontinuity method.

Syntax

HRESULT IsDiscontinuity(void);

Return Value

Returns S_OK if the sample is a break in the data stream, and S_FALSE otherwise.

Remarks

The m_dwFlags member variable specifies this property.

CMediaSample::IsPreroll

CMediaSample Class

Determines if this sample is a preroll sample. A preroll sample should not be displayed. Implements the IMediaSample::IsPreroll method.

Syntax

HRESULT IsPreroll(void);

Return Value

Returns S_OK if the sample is a preroll sample, and S_FALSE otherwise.

Remarks

The m_dwFlags member variable specifies this property.

CMediaSample::IsSyncPoint

CMediaSample Class

Determines if the beginning of the sample is a synchronization point. Implements the IMediaSample::IsSyncPoint method.

Syntax

HRESULT IsSyncPoint(void);

Return Value

Returns S_OK if the sample is a synchronization point, or S_FALSE otherwise.

Remarks

The m_dwFlags member variable specifies this property.

CMediaSample::SetActualDataLength

CMediaSample Class

Sets the length of the valid data in the buffer. Implements the IMediaSample::SetActualDataLength method.

Syntax

HRESULT SetActualDataLength(
    long lLen
);

Parameters

lLen
Length of the valid data, in bytes.

Return Value

Returns one of the HRESULT values shown in the following table.

S_OKSuccess.
VFW_E_BUFFER_OVERFLOWlLen is larger than the allocated buffer size.

Remarks

This method sets the m_lActual member variable.

CMediaSample::SetDiscontinuity

CMediaSample Class

Specifies whether this sample represents a break in the data stream. Implements the IMediaSample::SetDiscontinuity method.

Syntax

HRESULT SetDiscontinuity(
    BOOL bDiscont
);

Parameters

bDiscont
Boolean value that specifies whether this sample is a discontinuity. If TRUE, the media sample is discontinuous with the previous sample.

Return Value

Returns S_OK.

Remarks

This method updates the m_dwFlags member variable, which specifies the discontinuity property.

CMediaSample::SetMediaTime

CMediaSample Class

Sets the media times for this sample. Implements the IMediaSample::SetMediaTime method.

Syntax

HRESULT SetMediaTime(
    LONGLONG *pStart,
    LONGLONG *pEnd
);

Parameters

pStart
Pointer to the media start time, or NULL.
pEnd
Pointer to the media stop time, or NULL.

Return Value

Returns S_OK.

Remarks

The media stop time must be greater than the media start time. Use NULL to invalidate the media times.

The pEnd parameter specifies an absolute media time, but the m_MediaEnd member variable is calculated as an offset from pStart. In other words, m_MediaEnd = *pTimeEnd*pTimeStart.

For information about media times, see Time and Clocks in DirectShow.

CMediaSample::SetMediaType

CMediaSample Class

Sets the media type for the sample. Implements the IMediaSample::SetMediaType method.

Syntax

HRESULT SetMediaType(
    AM_MEDIA_TYPE *pMediaType
);

Parameters

pMediaType
Pointer to an AM_MEDIA_TYPE structure.

Return Value

Returns one of the HRESULT values shown in the following table.

S_OKSuccess
E_OUTOFMEMORYInsufficient memory

Remarks

This method sets the m_pMediaType member variable, which specifies the media type, and the m_dwFlags member variable, which specifies whether the media type has changed.

This method makes a copy of the AM_MEDIA_TYPE structure.

CMediaSample::SetPointer

CMediaSample Class

Sets the pointer to the memory buffer.

Syntax

HRESULT SetPointer(
    BYTE *ptr,
    LONG cBytes
); 

Parameters

ptr
Pointer to a memory buffer allocated by the caller, of size cBytes.
cBytes
Length of the buffer, in bytes.

Return Value

Returns S_OK.

Remarks

This method enables the allocator to set a new pointer for the sample.

This method is not available through the IMediaSample interface. The object that creates the sample can access this method (through CMediaSample), but other objects cannot.

CMediaSample::SetPreroll

CMediaSample Class

Specifies whether this sample is a preroll sample. A preroll sample should not be displayed. Implements the IMediaSample::SetPreroll method.

Syntax

HRESULT SetPreroll(
    BOOL bIsPreroll
);

Parameters

bIsPreroll
Boolean value that specifies whether this is a preroll sample. If TRUE, this is a preroll sample.

Return Value

Returns S_OK.

Remarks

This method updates the m_dwFlags member variable, which specifies the preroll property.

CMediaSample::SetProperties

CMediaSample Class

Sets the properties of the sample. This method implements the IMediaSample2::SetProperties method.

Syntax

HRESULT SetProperties(
    DWORD cbProperties,
    const BYTE *pbProperties
);

Parameters

cbProperties
Length of property data to set, in bytes.
pbProperties
Pointer to a buffer of size cbProperties.

Return Value

Returns one of the HRESULT values shown in the following table.

S_OKSuccess
E_INVALIDARGInvalid argument
E_OUTOFMEMORYInsufficient memory
E_POINTERNULL pointer argument

CMediaSample::SetSyncPoint

CMediaSample Class

Specifies whether the beginning of this sample is a synchronization point. This method implements the IMediaSample::SetSyncPoint method.

Syntax

HRESULT SetSyncPoint(
    BOOL bIsSyncPoint
);

Parameters

bIsSyncPoint
Boolean value that specifies whether this is a synchronization point. If TRUE, this is a synchronization point.

Return Value

Returns S_OK.

Remarks

This method updates the m_dwFlags member variable, which specifies the synchronization-point property.

CMediaSample::SetTime

CMediaSample Class

Sets the stream times when this sample should begin and finish. Implements the IMediaSample::SetTime method.

Syntax

HRESULT SetTime(
    REFERENCE_TIME *pTimeStart,
    REFERENCE_TIME *pTimeEnd
);

Parameters

pTimeStart
Pointer to the stream time at which the sample begins, in 100-nanosecond units, or NULL.
pTimeEnd
Pointer to the stream time at which the sample ends, in 100-nanosecond units, or NULL.

Return Value

Returns S_OK.

Remarks

This method sets the m_Start and m_End member variables, which specify the time stamps. It also updates the m_dwFlags member variable, which specifies whether the time stamps are valid.

For information about time stamps, see Time and Clocks in DirectShow.