This 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 normally 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
| Name | Description |
| 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_lActual | Actual length of data in this sample. |
| m_pAllocator | Pointer to the IMemAllocator object associated with this object. |
| 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_pBuffer | Pointer to the complete buffer. |
| m_End | Sample end time. |
| m_Start | Sample start time. |
| m_MediaStart | Media start position. |
| m_MediaEnd | Media end (offset from m_MediaStart). |
Member Functions
| Name | Description |
| CMediaSample | Constructs a CMediaSample object. |
| SetPointer | Sets the buffer pointer and length. |
Implemented IUnknown Methods
| Name | Description |
| QueryInterface | Returns pointers to supported interfaces. |
| AddRef | Increments the reference count. |
| Release | Decrements the reference count. |
Implemented IMediaSample Methods
| Name | Description |
| 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 | Returns 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
| Name | Description |
| NonDelegatingQueryInterface | Passes out pointers to any interfaces added to the derived filter class. |
Increments the reference count for the calling interface on an object.
ULONG AddRef(void);
Returns an integer from 1 to n, the value of the new reference count.
This member function implements the IUnknown::AddRef method.
Constructs a CMediaSample object.
CMediaSample(
TCHAR *pName,
CBaseAllocator *pAllocator,
HRESULT *phr,
LPBYTE pBuffer = NULL,
LONG length = 0
);
No return value.
The constructor creates an object with the buffer and buffer length set to that of the CBaseAllocator object to which it points.
Retrieves the data length of the sample.
HRESULT GetActualDataLength(void);
Returns the value of m_lActual by default.
This member function implements the IMediaSample::GetActualDataLength method.
Retrieves the starting and ending media time.
HRESULT GetMediaTime(
LONGLONG * pStart,
LONGLONG * pEnd
);
Returns an HRESULT value.
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.
Retrieves the media type of the CMediaSample object.
HRESULT GetMediaType(
AM_MEDIA_TYPE ** ppMediaType
);
Returns an HRESULT value. When a sample is received and there is no format change, this method returns S_FALSE.
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.
Retrieves a read/write pointer to the buffer's memory.
HRESULT GetPointer(
BYTE ** ppBuffer
);
Returns VFW_E_BUFFER_NOTSET if CMediaSample::SetPointer was not called before calling this function, or NOERROR otherwise.
This member function implements the IMediaSample::GetPointer method. GetPointer returns the value of m_pBuffer, set using CMediaSample::SetPointer.
Retrieves the size, in bytes, of the buffer data area.
HRESULT GetSize(void);
Returns the value of m_cbBuffer by default.
This member function implements the IMediaSample::GetSize method.
Retrieves the stream time at which this sample should begin and finish.
HRESULT GetTime(
REFERENCE_TIME * pTimeStart,
REFERENCE_TIME * pTimeEnd
);
Returns VFW_E_SAMPLE_TIME_NOT_SET if this sample doesn't have valid timestamps, or NOERROR otherwise.
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.
Determines if there is discontinuity in the data stream.
HRESULT IsDiscontinuity(void);
Returns S_OK if the sample is a discontinuous sample and S_FALSE if not; otherwise, returns an HRESULT error value.
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.
Preroll property. If TRUE, this sample is for preroll only and should not be displayed.
HRESULT IsPreroll(void);
Returns S_OK if the sample is a preroll sample and S_FALSE if not; otherwise, returns an HRESULT error value.
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.
Determines if the beginning of a sample is a synchronization point.
HRESULT IsSyncPoint(void);
Returns S_OK if the sample is a synchronization point and S_FALSE if not; otherwise, returns an HRESULT error value.
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.
Retrieves an interface and increments the reference count.
HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);
Returns a pointer to the interface.
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.
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.
HRESULT QueryInterface(
REFIID iid,
void ** ppvObject
);
Returns S_OK if the interface is supported, S_FALSE if not.
This member function implements the IUnknown::QueryInterface method.
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.
ULONG Release(void);
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.
This member function implements the IUnknown::Release method.
Sets the data length of the sample.
HRESULT SetActualDataLength(
long lLen
);
Returns an HRESULT value.
This member function implements the IMediaSample::SetActualDataLength method. It sets the value of m_lActual to the value of lLen.
Sets the discontinuity property.
HRESULT SetDiscontinuity(
BOOL bDiscont
);
Returns an HRESULT value.
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.
Sets the starting and ending media times.
HRESULT SetMediaTime(
LONGLONG * pStart,
LONGLONG * pEnd
);
Returns an HRESULT value.
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.
Sets the media type for the CMediaSample object.
HRESULT SetMediaType(
AM_MEDIA_TYPE * pMediaType
);
Returns an HRESULT value.
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.
Sets the buffer pointer and length.
SetPointer(
BYTE * ptr,
LONG cBytes
);
No return value.
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).
Sets the preroll property. If TRUE, this sample is for preroll only and should not be displayed.
HRESULT SetPreroll(
BOOL bIsPreroll
);
Returns an HRESULT value.
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.
Property of a synchronization point.
HRESULT SetSyncPoint(
BOOL bIsSyncPoint
);
Returns S_OK.
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.
Sets the media time extents for this sample.
HRESULT SetTime(
REFERENCE_TIME * pTimeStart,
REFERENCE_TIME * pTimeEnd
);
Returns NOERROR or an HRESULT value.
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, DirectShow turns off the m_dwFlags data member's Sample_TimeValid and Sample_StopValid bits.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.