CMediaSample Class

CMediaSample class hierarchy

The CMediaSample class represents a buffer object that supports the IMediaSample interface. It represents a buffer in memory, together with some associated properties stored as protected data members.

The constructor is passed as a pointer to the buffer with its length in bytes; other properties are typically set and accessed through implemented IMediaSample interface methods. These properties describe various attributes of the media sample, such as the sample's media type, start and end time, and options. The options can include whether the media sample is a sync point, a preroll sample, or discontinuous with other samples.

All member functions in this class that return HRESULT and accept a pointer as a parameter return E_POINTER when passed a null pointer.

Protected Data Members

m_cbBuffer Size of the buffer.

m_dwFlags Sample property flags as follows:
Sample_Discontinuity: Set if start of a new segment.
Sample_MediaTimeValid: Set if the media time is valid.
Sample_Preroll: Set if sample is a preroll sample.
Sample_StopValid: Set if the stop time is valid.
Sample_SyncPoint: Set if sample is a synchronization point.
Sample_TimeValid: Set if the time is valid.
Sample_TypeChanged: Set if the type has changed.

m_End Sample end time.

m_lActual Actual length of data in this sample.

m_MediaEnd Media end (offset from m_MediaStart).

m_MediaStart Media start position.

m_pAllocator Pointer to the IMemAllocator object associated with this object.

m_pBuffer Pointer to the complete buffer.

m_pMediaType Pointer to a structure containing the media type of the sample.

m_pNext Pointer to the next CMediaSample object in the free list.

m_Start Sample start time.

Member Functions

CMediaSample Constructs a CMediaSample object.
SetPointer Sets the buffer pointer and length.

Implemented IUnknown Methods

QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.

Implemented IMediaSample Methods

GetActualDataLength Retrieves the data length of the sample.
GetMediaTime Retrieves the media time extents of the sample.
GetMediaType Retrieves the media type of the CMediaSample object.
GetPointer Retrieves a read/write pointer to the memory of this buffer.
GetSize Retrieves the size, in bytes, of the buffer data area.
GetTime Sets the media time extents for this sample.
IsDiscontinuity Determines if there is discontinuity in the data stream.
IsPreroll Indicates a preroll property. If TRUE, this sample is for preroll only and should not be displayed.
IsSyncPoint Determines if the beginning of a sample is a synchronization point.
SetActualDataLength Sets the data length of the sample.
SetDiscontinuity Sets the discontinuity property.
SetMediaTime Sets the media time of the CMediaSample object.
SetMediaType Sets the media type of the CMediaSample object.
SetPreroll Sets preroll property. If TRUE, this sample is for preroll only and should not be displayed.
SetSyncPoint Sets sync-point property.
SetTime Sets the stream time at which this sample should start and finish.

Implemented INonDelegatingUnknown Methods

NonDelegatingQueryInterface Passes out pointers to any interfaces added to the derived filter class.

CMediaSample::AddRef

CMediaSample Class

Increments the reference count for the calling interface on an object.

Syntax

ULONG AddRef(void);

Return Value

Returns an integer from 1 to n, the value of the new reference count.

Remarks

This member function implements the IUnknown::AddRef method.

CMediaSample::CMediaSample

CMediaSample Class

Constructs a CMediaSample object.

Syntax

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

Parameters

pName
Pointer to the name of the media sample.
pAllocator
Pointer to the CBaseAllocator object used for memory allocation.
phr
Pointer to the general COM return value. Note that this value is changed only if this function fails.
pBuffer
Pointer to a memory buffer (to be allocated by the pAllocator parameter).
length
Length of the allocated memory buffer.

Return Value

No return value.

Remarks

The constructor creates an object with the buffer and buffer length set to that of the CBaseAllocator object to which it points.

CMediaSample::GetActualDataLength

CMediaSample Class

Retrieves the data length of the sample.

Syntax

HRESULT GetActualDataLength(void);

Return Value

Returns the value of m_lActual by default.

Remarks

This member function implements the IMediaSample::GetActualDataLength method.

CMediaSample::GetMediaTime

CMediaSample Class

Retrieves the starting and ending media time.

Syntax

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

Parameters

pStart
Pointer to the retrieved beginning media time.
pEnd
Pointer to the retrieved ending media time.

Return Value

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::GetMediaTime method. It sets pStart to the current value of m_MediaStart and pEnd to the sum of m_MediaStart and m_MediaEnd. If the sample has not been set, this member function returns VFW_E_MEDIA_TIME_NOT_SET.

CMediaSample::GetMediaType

CMediaSample Class

Retrieves the media type of the CMediaSample object.

Syntax

HRESULT GetMediaType(
    AM_MEDIA_TYPE **ppMediaType
);

Parameters

ppMediaType
Address of a pointer to a pointer to the retrieved media type.

Return Value

Returns an HRESULT value. When a sample is received and there is no format change, this method returns S_FALSE.

Remarks

This member function implements the IMediaSample::GetMediaType method. The member function makes a copy of the AM_MEDIA_TYPE structure and creates a task memory block to maintain the reference. When you are done with the media type, free the memory block with the FreeMediaType utility function, and then free the entire media type with the Microsoft® Win32® CoTaskMemFree function.

CMediaSample::GetPointer

CMediaSample Class

Retrieves a read/write pointer to the buffer's memory.

Syntax

HRESULT GetPointer(
    BYTE **ppBuffer
);

Parameters

ppBuffer
Address of a pointer to the buffer.

Return Value

Returns VFW_E_BUFFER_NOTSET if CMediaSample::SetPointer was not called before calling this function, or NOERROR otherwise.

Remarks

This member function implements the IMediaSample::GetPointer method. GetPointer returns the value of m_pBuffer, set using CMediaSample::SetPointer.

CMediaSample::GetSize

CMediaSample Class

Retrieves the size, in bytes, of the buffer data area.

Syntax

HRESULT GetSize(void);

Return Value

Returns the value of m_cbBuffer by default.

Remarks

This member function implements the IMediaSample::GetSize method.

CMediaSample::GetTime

CMediaSample Class

Retrieves the stream time at which this sample should begin and finish.

Syntax

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

Parameters

pTimeStart
Pointer to the retrieved beginning stream time.
pTimeEnd
Pointer to the retrieved ending stream time.

Return Value

Returns VFW_E_SAMPLE_TIME_NOT_SET if this sample doesn't have valid timestamps, or NOERROR otherwise.

Remarks

This member function implements the IMediaSample::GetTime method. It sets pTimeStart to the current value of m_Start and pTimeEnd to the current value of m_End.

CMediaSample::IsDiscontinuity

CMediaSample Class

Determines if there is discontinuity in the data stream.

Syntax

HRESULT IsDiscontinuity(void);

Return Value

Returns S_OK if the sample is a discontinuous sample and S_FALSE if not; otherwise, returns an HRESULT error value.

Remarks

This member function implements the IMediaSample::IsDiscontinuity method. It returns the value of the m_dwFlags Sample_Discontinuity property flag. Discontinuity occurs when a source filter seeks to a different place in the stream or when a filter drops samples for quality control.

CMediaSample::IsPreroll

CMediaSample Class

Indicates a preroll property. If TRUE, this sample is for preroll only and should not be displayed.

Syntax

HRESULT IsPreroll(void);

Return Value

Returns S_OK if the sample is a preroll sample and S_FALSE if not; otherwise, returns an HRESULT error value.

Remarks

This member function implements the IMediaSample::IsPreroll method. It returns the value of the m_dwFlags Sample_Preroll property flag. Preroll samples are not meant to be rendered.

CMediaSample::IsSyncPoint

CMediaSample Class

Determines if the beginning of a sample is a synchronization point.

Syntax

HRESULT IsSyncPoint(void);

Return Value

Returns S_OK if the sample is a synchronization point and S_FALSE if not; otherwise, returns an HRESULT error value.

Remarks

This member function implements the IMediaSample::IsSyncPoint method. It returns the value of the m_dwFlags Sample_SyncPoint property flag. If the bTemporalCompression member of the AM_MEDIA_TYPE structure is FALSE, all samples are synchronization points. A filter can begin a stream at any synchronization point.

CMediaSample::NonDelegatingQueryInterface

CMediaSample Class

Retrieves an interface and increments the reference count.

Syntax

HRESULT NonDelegatingQueryInterface(
    REFIID riid,
    void **ppv
);

Parameters

riid
Reference identifier.
ppv
Address of a pointer to the interface.

Return Value

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method and passes out references to the IMediaSample and IUnknown interfaces. Override this class to return other interfaces on the object in the derived class.

CMediaSample::QueryInterface

CMediaSample Class

Retrieves a pointer to a specified interface on a component to which a client currently holds an interface pointer. This method must call IUnknown::AddRef on the pointer it returns.

Syntax

HRESULT QueryInterface(
    REFIID iid,
    void **ppvObject
);

Parameters

iid
Interface identifier (IID) of the interface being requested.
ppvObject
Address of a pointer to the object on return. If the interface specified in iid is not supported by the object, ppvObject is set to NULL.

Return Value

Returns S_OK if the interface is supported, S_FALSE if not.

Remarks

This member function implements the IUnknown::QueryInterface method.

CMediaSample::Release

CMediaSample Class

Decrements the reference count for the calling interface on an object. If the reference count on the object falls to zero, the object is freed from memory.

Syntax

ULONG Release(void);

Return Value

Returns the resulting value of the reference count, which is used for diagnostic/testing purposes only. If you need to know that resources have been freed, use an interface with higher-level semantics.

Remarks

This member function implements the IUnknown::Release method.

CMediaSample::SetActualDataLength

CMediaSample Class

Sets the data length of the sample.

Syntax

HRESULT SetActualDataLength(
    long lLen
);

Parameters

lLen
Length of the data in the media sample, in bytes.

Return Value

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::SetActualDataLength method. It sets the value of m_lActual to the value of lLen.

CMediaSample::SetDiscontinuity

CMediaSample Class

Sets the discontinuity property.

Syntax

HRESULT SetDiscontinuity(
    BOOL bDiscont
);

Parameters

bDiscont
Value specifying the discontinuity; set to TRUE to specify the media sample as discontinuous with the previous sample.

Return Value

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::SetDiscontinuity method. It sets the value of the m_dwFlags Sample_Discontinuity flag to the value of bDiscont. Discontinuous samples occur when a source filter seeks to a different place in the media stream or when a filter drops samples for quality control.

CMediaSample::SetMediaTime

CMediaSample Class

Sets the starting and ending media times.

Syntax

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

Parameters

pStart
Pointer to the beginning media time.
pEnd
Pointer to the ending media time.

Return Value

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::SetMediaTime method. It sets the m_MediaStart data member to the value of pStart and the m_MediaEnd data member to the value of pEnd minus pStart.

CMediaSample::SetMediaType

CMediaSample Class

Sets the media type for the CMediaSample object.

Syntax

HRESULT SetMediaType(
    AM_MEDIA_TYPE *pMediaType
);

Parameters

pMediaType
Pointer to a media type structure to be set.

Return Value

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::SetMediaType method. It deletes the previous media type if one exists, makes a copy of the media type passed in, sets m_pMediaType to the copy of the media type, and sets the value of the m_dwFlags Sample_TypeChanged flag to TRUE.

CMediaSample::SetPointer

CMediaSample Class

Sets the buffer pointer and length.

Syntax

SetPointer(
    BYTE *ptr,
    LONG cBytes
);

Parameters

ptr
Pointer to a buffer.
cBytes
Length of the buffer, in bytes.

Return Value

No return value.

Remarks

Allocators that require variable-sized pointers or pointers into data that has already been read use this member function. This is available only through a CMediaSample class, not an IMediaSample interface, so only the filter that owns the allocator knows how to access this member function (not any filter or pin that is passed the object's IMediaSample interface pointer).

CMediaSample::SetPreroll

CMediaSample Class

Sets the preroll property. If TRUE, this sample is for preroll only and should not be displayed.

Syntax

HRESULT SetPreroll(
    BOOL bIsPreroll
);

Parameters

bIsPreroll
Value specifying preroll; set to TRUE to specify the media sample as a preroll sample, or FALSE otherwise.

Return Value

Returns an HRESULT value.

Remarks

This member function implements the IMediaSample::SetPreroll method. It sets the value of the m_dwFlags Sample_Preroll flag to the value of bIsPreroll. Preroll samples are samples that are processed but not displayed, and are located in the media stream before the displayable samples.

CMediaSample::SetSyncPoint

CMediaSample Class

Property of a synchronization point.

Syntax

HRESULT SetSyncPoint(
    BOOL bIsSyncPoint
);

Parameters

bIsSyncPoint
Value specifying whether the synchronization point was set; TRUE means it was.

Return Value

Returns S_OK.

Remarks

This member function implements the IMediaSample::SetSyncPoint method. It sets the value of the m_dwFlags Sample_SyncPoint flag to the value of bIsSyncPoint. A filter can begin a stream at any synchronization point.

CMediaSample::SetTime

CMediaSample Class

Sets the media time extents for this sample.

Syntax

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

Parameters

pTimeStart
Pointer to the stream time at which the sample begins.
pTimeEnd
Pointer to the stream time at which the sample ends.

Return Value

Returns NOERROR or an HRESULT value.

Remarks

This member function implements the IMediaSample::SetTime method. It sets the m_Start data member to the value of pTimeStart and the m_End data member to the value of pTimeEnd.
If pTimeStart and pTimeEnd are null, Microsoft® DirectShow® turns off the m_dwFlags data member's Sample_TimeValid and Sample_StopValid bits.

m_cbBuffer	Size of the buffer.
m_dwFlags	Sample property flags as follows: Sample_Discontinuity: Set if start of a new segment. Sample_MediaTimeValid: Set if the media time is valid. Sample_Preroll: Set if sample is a preroll sample. Sample_StopValid: Set if the stop time is valid. Sample_SyncPoint: Set if sample is a synchronization point. Sample_TimeValid: Set if the time is valid. Sample_TypeChanged: Set if the type has changed.
m_End	Sample end time.
m_lActual	Actual length of data in this sample.
m_MediaEnd	Media end (offset from m_MediaStart).
m_MediaStart	Media start position.
m_pAllocator	Pointer to the IMemAllocator object associated with this object.
m_pBuffer	Pointer to the complete buffer.
m_pMediaType	Pointer to a structure containing the media type of the sample.
m_pNext	Pointer to the next CMediaSample object in the free list.
m_Start	Sample start time.

CMediaSample	Constructs a CMediaSample object.
SetPointer	Sets the buffer pointer and length.

QueryInterface	Retrieves pointers to supported interfaces.
AddRef	Increments the reference count.
Release	Decrements the reference count.

GetActualDataLength	Retrieves the data length of the sample.
GetMediaTime	Retrieves the media time extents of the sample.
GetMediaType	Retrieves the media type of the CMediaSample object.
GetPointer	Retrieves a read/write pointer to the memory of this buffer.
GetSize	Retrieves the size, in bytes, of the buffer data area.
GetTime	Sets the media time extents for this sample.
IsDiscontinuity	Determines if there is discontinuity in the data stream.
IsPreroll	Indicates a preroll property. If TRUE, this sample is for preroll only and should not be displayed.
IsSyncPoint	Determines if the beginning of a sample is a synchronization point.
SetActualDataLength	Sets the data length of the sample.
SetDiscontinuity	Sets the discontinuity property.
SetMediaTime	Sets the media time of the CMediaSample object.
SetMediaType	Sets the media type of the CMediaSample object.
SetPreroll	Sets preroll property. If TRUE, this sample is for preroll only and should not be displayed.
SetSyncPoint	Sets sync-point property.
SetTime	Sets the stream time at which this sample should start and finish.