The IMediaSample interface provides shared memory buffer functionality, holds some properties about the data, and holds a pointer to the data itself. It is used by connected pins to transport media samples from one pin to another.
The IMediaSample2 interface extends the functionality of this interface to allow you to set and to retrieve media sample properties.
When to Implement
Implement this interface if you are providing an allocator (buffer) to be used for transporting media samples between filters. This interface is implemented by the CMediaSample class in the DirectShow™ class library.
When to Use
Filters use methods on this interface to set properties and pass data to another filter. Downstream filters use methods on this interface to read the media sample's data and properties. Filters can modify the data in a media sample in place or can make a copy of the sample, modify the copy, and pass it on.
Methods in Vtable Order
| IUnknown methods | Description |
| QueryInterface | Returns 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 | Returns the size, in bytes, of the buffer data area. |
| GetTime | Retrieves the stream times at which this sample should begin and finish. |
| SetTime | Sets the stream times at which this sample should begin and finish. |
| IsSyncPoint | Determines if the beginning of a sample is a synchronization point. |
| SetSyncPoint | Sets the synchronization point. |
| IsPreroll | Indicates a preroll property. If TRUE, this sample is for preroll only and should not be displayed. |
| SetPreroll | Sets the preroll property. If TRUE, this sample is for preroll only and should not be displayed. |
| GetActualDataLength | Retrieves the data length of the sample. |
| SetActualDataLength | Sets the data length of the sample. |
| GetMediaType | Retrieves the media type of the sample. |
| SetMediaType | Sets the media type of the sample. |
| IsDiscontinuity | Indicates a discontinuity property. If S_OK is returned, sample is not contiguous with previous sample. |
| SetDiscontinuity | Sets the discontinuity property. Set to TRUE if sample is new after a seek or dropped sample. |
| GetMediaTime | Retrieves the media time stamps for the sample. |
| SetMediaTime | Sets the media time stamps for the sample. |
Retrieves the data length of the sample.
HRESULT GetActualDataLength(void);
Returns an HRESULT value that is the length.
Note that although this is typed as returning an HRESULT value, it actually returns the length in bytes, not an error value.
Retrieves the media time stamps for this sample.
HRESULT GetMediaTime(
LONGLONG * pTimeStart,
LONGLONG * pTimeEnd
);
Returns NOERROR if the sample contains valid time stamps. Returns VFW_E_MEDIA_TIME_NOT_SET if the time has not been set in the sample.
Retrieves the media type of the IMediaSample 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 method allows for limited in-band format changes. Free the format block with FreeMediaType, and then free the entire media type with the Microsoft® Win32® CoTaskMemFree function.
Retrieves a read/write pointer to this buffer's memory.
HRESULT GetPointer(
BYTE ** ppBuffer
);
Returns an HRESULT value.
Returns the size, in bytes, of the buffer data area.
HRESULT GetSize(void);
Returns an HRESULT value.
Note that although this is typed as returning an HRESULT value, it actually returns the length in bytes, not an error value.
Retrieves the stream times at which this sample should begin and finish.
HRESULT GetTime(
REFERENCE_TIME * pTimeStart,
REFERENCE_TIME * pTimeEnd
);
Returns NOERROR if the sample contains valid time stamps. Returns VFW_E_MEDIA_TIME_NOT_SET if the time has not been set in the sample.
Determines if there is discontinuity in the data stream.
HRESULT IsDiscontinuity(void);
Returns S_OK if the sample is a discontinuous sample, or S_FALSE if not; otherwise, returns an HRESULT error value.
Discontinuity occurs when a source filter seeks to a different place in the stream or when a filter drops samples for quality control.
Note that while calling SetDiscontinuity with a value of TRUE (1) sets the discontinuity property, calling IsDiscontinuity on a discontinuous sample returns S_OK (0).
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, or S_FALSE if not; otherwise, returns an HRESULT error value. Note that while calling SetPreroll with a value of TRUE (1) sets the preroll property, calling IsPreroll on a preroll sample returns S_OK (0).
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.
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.
Note that while calling SetSyncPoint with a value of TRUE (1) sets the synchronization point, calling IsSyncPoint on a synchronization point sample returns S_OK (0).
Sets the sample's data length.
HRESULT SetActualDataLength(
long lLen
);
Returns an HRESULT value.
Sets the discontinuity property.
HRESULT SetDiscontinuity(
BOOL bIsDiscontinuity
);
Returns an HRESULT value.
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.
Note that while calling SetDiscontinuity with a value of TRUE (1) sets the discontinuity property, calling IsDiscontinuity on a discontinuous sample returns S_OK (0).
Sets the media time stamps for this sample.
HRESULT SetMediaTime(
LONGLONG * pTimeStart,
LONGLONG * pTimeEnd
);
Returns an HRESULT value.
To reset the time, use this method with both pTimeStart and pTimeEnd set to NULL. This will cause IMediaSample::GetMediaTime to return an error.
Sets the media type for the IMediaSample object.
HRESULT SetMediaType(
AM_MEDIA_TYPE * pMediaType
);
Returns an HRESULT value.
This method allows for limited in-band format changes.
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.
Preroll samples are samples that are processed but not displayed, and are located in the media stream before the displayable samples.
Note that while calling SetPreroll with a value of TRUE (1) sets the preroll property, calling IsPreroll on a preroll sample returns S_OK (0).
Property of a synchronization point.
HRESULT SetSyncPoint(
BOOL bIsSyncPoint
);
Returns S_OK.
A filter can begin a stream at any synchronization point. Note that while calling SetSyncPoint with a value of TRUE (1) sets the synchronization point, calling IsSyncPoint on a synchronization point sample returns S_OK (0).
Sets the stream time when this sample should begin and finish.
HRESULT SetTime(
REFERENCE_TIME * pTimeStart,
REFERENCE_TIME * pTimeEnd
);
Returns an HRESULT value.
To reset the time, use this method with both pTimeStart and pTimeEnd set to NULL. This will cause IMediaSample::GetTime to return VFW_S_NO_STOP_TIME.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.