CMediaSample class

[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.]

The CMediaSample class 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.

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:

• The allocator holds a list of free samples. When a filter needs a new sample, it calls the allocator's IMemAllocator::GetBuffer method. The allocator retrieves a sample from its free list, increments the sample's reference count, and returns a pointer to the sample.
• After the filter is done with the sample, it calls the IUnknown::Release method on the sample. Unlike most objects, the sample does not delete itself when its reference count reaches zero. Instead, it calls the IMemAllocator::ReleaseBuffer method on the allocator, and the allocator returns the sample to its free list.
• The allocator does not destroy samples until the IMemAllocator::Decommit method is called.

Protected Member Variables	Description
m_dwFlags	Sample property flags.
m_dwTypeSpecificFlags	Type-specific flags.
m_pBuffer	Pointer to the memory buffer that contains the media data.
m_lActual	Length of the valid data in the buffer, in bytes.
m_cbBuffer	Size of the buffer, in bytes.
m_pAllocator	Pointer to the allocator that created this sample.
m_pNext	Pointer to the next sample in the allocator's list of samples.
m_Start	Sample start time.
m_End	Sample end time.
m_MediaStart	Media start time.
m_MediaEnd	Media stop time.
m_pMediaType	Pointer to the media type, if the type has changed from the previous sample in the data stream.
m_dwStreamId	Stream identifier.
Public Member Variables	Description
m_cRef	Reference count.
Public Methods	Description
CMediaSample	Constructor method.
~ CMediaSample	Destructor method. Virtual.
SetPointer	Sets the pointer to the memory buffer.
IMediaSample Methods	Description
GetPointer	Retrieves a read/write pointer to the buffer.
GetSize	Retrieves the size of the buffer.
GetTime	Retrieves the stream times at which this sample should begin and finish.
SetTime	Sets the stream times at which this sample should start and finish.
IsSyncPoint	Determines if the beginning of the sample is a synchronization point.
SetSyncPoint	Specifies whether the beginning of this sample is a synchronization point.
IsPreroll	Determines if this sample is a preroll sample.
SetPreroll	Specifies whether this sample is a preroll sample.
GetActualDataLength	Retrieves the length of the valid data in the buffer.
SetActualDataLength	Sets the length of the valid data in the buffer.
GetMediaType	Retrieves the media type, if the media type differs from the previous sample.
SetMediaType	Sets the media type for the sample.
IsDiscontinuity	Determines if this sample represents a break in the data stream.
SetDiscontinuity	Specifies whether this sample represents a break in the data stream.
GetMediaTime	Retrieves the media times for this sample.
SetMediaTime	Sets the media times for this sample.
IMediaSample2 Methods	Description
GetProperties	Retrieves the properties of the sample.
SetProperties	Sets the properties of the sample.

Requirements

Requirement	Value
Header	Amfilter.h (include Streams.h)
Library	Strmbase.lib (retail builds); Strmbasd.lib (debug builds)