Microsoft DirectX 8.0 |
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_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 | |
m_cRef | Reference count. |
Public Methods | |
CMediaSample | Constructor method. |
~CMediaSample | Destructor method. Virtual. |
SetPointer | Sets the pointer to the memory buffer. |
IMediaSample Methods | |
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 | |
GetProperties | Retrieves the properties of the sample. |
SetProperties | Sets the properties of the sample. |
Sample property flags. Bitwise combination of flags from the AM_SAMPLE_PROPERTY_FLAGS enumerated type.
Syntax
DWORD m_dwFlags;
Type-specific flags. The meaning of this member variable depends on the media type of the sample.
Syntax
DWORD m_dwTypeSpecificFlags;
Pointer to the memory buffer that contains the media data.
Syntax
LPBYTE m_pBuffer;
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;
Size of the buffer, in bytes.
Syntax
LONG m_cbBuffer;
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.
Pointer to the next sample in the allocator's list of samples.
Syntax
CMediaSample *m_pNext;
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;
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;
Media start time.
Syntax
LONGLONG m_MediaStart;
Media stop time. This value is calculated as an offset from the media start time (m_MediaStart).
Syntax
LONG m_MediaEnd;
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;
Stream identifier. For more information, see AM_SAMPLE2_PROPERTIES.
Syntax
DWORD m_dwStreamId;
Reference count.
Syntax
LONG m_cRef;
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.
Destructor method.
Syntax
~CMediaSample(void);
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.
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_OK Success. VFW_E_MEDIA_TIME_NOT_SET No 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.
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_FALSE The media type has not changed from the previous sample. S_OK Success. E_OUTOFMEMORY Insufficient 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.
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.
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_OK Success. E_POINTER NULL pointer argument.
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.
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_OK Success. VFW_S_NO_STOP_TIME Sample has a valid start time, but no stop time. VFW_E_SAMPLE_TIME_NOT_SET Sample 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.
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.
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.
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.
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_OK Success. VFW_E_BUFFER_OVERFLOW lLen is larger than the allocated buffer size.
Remarks
This method sets the m_lActual member variable.
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.
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.
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_OK Success E_OUTOFMEMORY Insufficient 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.
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.
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.
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_OK Success E_INVALIDARG Invalid argument E_OUTOFMEMORY Insufficient memory E_POINTER NULL pointer argument
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.
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.