Microsoft DirectX 8.0 |
Sets and retrieves properties on media samples. A media sample is a COM object that contains a block of media data. Media samples support the use of shared memory buffers among filters.
Typically, applications do not call methods on this interface. Filters use this interface to set properties on samples, and deliver the samples to a downstream filter. The downstream filter uses the interface to retrieve the properties and read the data. The filter can modify the data in place, or it can copy the sample, modify the copy, and pass the copy downstream.
The IMediaSample2 interface inherits this interface.
Methods in Vtable Order
IUnknown methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IMediaSample methods Description GetPointer Retrieves a read/write pointer to this buffer's memory. GetSize Retrieves the size of the buffer. GetTime Retrieves the stream times at which this sample should begin and finish. SetTime Sets the stream time when this sample should begin and finish. IsSyncPoint Determines if the beginning of this 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.
Retrieves the length of the valid data in the buffer.
Syntax
LONG GetActualDataLength(void);
Return Value
Returns the length of the valid data, in bytes.
Retrieves the media times for this sample.
Syntax
HRESULT GetMediaTime( LONGLONG *pTimeStart, LONGLONG *pTimeEnd );
Parameters
- pTimeStart
- [out] Pointer to a variable that receives the media start time.
- pTimeEnd
- [out] Pointer to a variable that receives the media stop time.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success. VFW_E_MEDIA_TIME_NOT_SET Media times are not set on this sample. Remarks
For more information about media times, see Time and Clocks in DirectShow.
IMediaSample::GetMediaType
Retrieves the media type, if the media type differs from the previous sample.
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 an HRESULT value. Possible values include those 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
This method enables a filter to make limited changes to the media type, such as changing the palette. To make a significant change to the media type, the pins might need to reconnect and renegotiate the media type.
When you are done with the media type, free the memory block by calling the DeleteMediaType utility function.
IMediaSample::GetPointer
Retrieves a read/write pointer to this buffer's memory.
Syntax
HRESULT GetPointer( BYTE **ppBuffer );Parameters
- ppBuffer
- [out] Address of a pointer to the buffer.
Return Value
Returns S_OK if successful, or an HRESULT value indicating the cause of the error.
IMediaSample::GetSize
Retrieves the size of the buffer.
Syntax
long GetSize(void);Return Value
Returns the size of the buffer, in bytes.
IMediaSample::GetTime
Retrieves the stream times at which this sample should begin and finish.
Syntax
HRESULT GetTime( REFERENCE_TIME *pTimeStart, REFERENCE_TIME *pTimeEnd );Parameters
- pTimeStart
- [out] Pointer to a variable that receives the beginning stream time.
- pTimeEnd
- [out] Pointer to a variable that receives the ending stream time. If the sample has no stop time, the value is set to the start time plus one.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success. The sample has valid start and stop times. VFW_S_NO_STOP_TIME The sample has a valid start time, but no stop time. VFW_E_SAMPLE_TIME_NOT_SET The sample is not time-stamped. Remarks
For more information about stream times, see Time and Clocks in DirectShow.
IMediaSample::IsDiscontinuity
Determines if this sample represents a break in the data stream.
Syntax
HRESULT IsDiscontinuity(void);Return Value
Returns S_OK if the sample is a break in the data stream. Otherwise, returns S_FALSE.
Remarks
A discontinuity occurs when a filter seeks to a different place in the stream, or when a filter drops samples for quality control.
IMediaSample::IsPreroll
Determines if this sample is a preroll sample. A preroll sample should not be displayed.
Syntax
HRESULT IsPreroll(void);Return Value
Returns S_OK if the sample is a preroll sample. Otherwise, returns S_FALSE.
Remarks
Preroll samples are processed but not displayed. They are located in the media stream before the displayable samples.
IMediaSample::IsSyncPoint
Determines if the beginning of this sample is a synchronization point.
Syntax
HRESULT IsSyncPoint(void);Return Value
Returns S_OK if the sample is a synchronization point. Otherwise, returns S_FALSE.
Remarks
A filter can begin a stream at any synchronization point. With some compression types, streaming can begin only at certain points in the stream; for example, on key frames. If the bTemporalCompression member of the AM_MEDIA_TYPE structure is FALSE, all samples are synchronization points.
IMediaSample::SetActualDataLength
Sets the length of the valid data in the buffer.
Syntax
HRESULT SetActualDataLength( long lLen );Parameters
- lLen
- Length of the data in the media sample, in bytes.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success. VFW_E_BUFFER_OVERFLOW. Length specified in lLen is larger than the buffer size. IMediaSample::SetDiscontinuity
Specifies whether this sample represents a break in the data stream.
Syntax
HRESULT SetDiscontinuity( BOOL bIsDiscontinuity );Parameters
- bIsDiscontinuity
- [in] 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, or an HRESULT value indicating the cause of the error.
See Also
IMediaSample::SetMediaTime
Sets the media times for this sample.
Syntax
HRESULT SetMediaTime( LONGLONG *pTimeStart, LONGLONG *pTimeEnd );
Parameters
- pTimeStart
- [in] Pointer to the beginning media time.
- pTimeEnd
- [in] Pointer to the ending media time.
Return Value
Returns S_OK, or an HRESULT value indicating the cause of the error.
Remarks
To invalidate the media time, set pTimeStart and pTimeEnd to NULL. This will cause the IMediaSample::GetMediaTime method to return VFW_E_MEDIA_TIME_NOT_SET.
For more information about media times, see Time and Clocks in DirectShow.
IMediaSample::SetMediaType
Sets the media type for the sample.
Syntax
HRESULT SetMediaType( AM_MEDIA_TYPE *pMediaType );Parameters
- pMediaType
- Pointer to an AM_MEDIA_TYPE structure that specifies the media type.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success E_OUTOFMEMORY Insufficient memory Remarks
By default, every sample has the same media type as the previous sample. (The pin connection determines the original media type.) Call this method to make limited changes to the media type, such as changing the palette. To make a significant change to the media type, the pins might need to reconnect and renegotiate the media type.
IMediaSample::SetPreroll
Specifies whether this sample is a preroll sample.
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, or an HRESULT value indicating the cause of the error.
See Also
IMediaSample::SetSyncPoint
Specifies whether the beginning of this sample is a synchronization point.
Syntax
HRESULT SetSyncPoint( BOOL bIsSyncPoint );Parameters
- bIsSyncPoint
- [in] Boolean value that specifies whether this is a synchronization point. If TRUE, this is a synchronization point.
Return Value
Returns S_OK or an HRESULT value indicating the cause of the error.
See Also
IMediaSample::SetTime
Sets the stream times when this sample should begin and finish.
Syntax
HRESULT SetTime( REFERENCE_TIME *pTimeStart, REFERENCE_TIME *pTimeEnd );Parameters
- pTimeStart
- [in] Pointer to the stream time at which the sample begins, in 100-nanosecond units.
- pTimeEnd
- [in] Pointer to the stream time at which the sample ends, in 100-nanosecond units.
Return Value
Returns S_OK, or HRESULT value indicating the cause of the error.
Remarks
To invalidate the stream times, set pTimeStart and pTimeEnd to NULL. This will cause the IMediaSample::GetTime method to return VFW_E_SAMPLE_TIME_NOT_SET.
For more information about stream times, see Time and Clocks in DirectShow.