IMediaSample Interface

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 enable you to set and retrieve media sample properties.

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 Microsoft® DirectShow® class library.

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 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, 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.

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, 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.

IMediaSample::GetActualDataLength

IMediaSample Interface

Retrieves the data length of the sample.

Syntax

HRESULT GetActualDataLength(void);

Return Value

Returns an HRESULT value that is the length.

Remarks

Although this is typed as returning an HRESULT value, it actually returns the length in bytes, not an error value.

IMediaSample::GetMediaTime

IMediaSample Interface

Retrieves the media time stamps for this sample.

Syntax

HRESULT GetMediaTime(
    LONGLONG *pTimeStart,
    LONGLONG *pTimeEnd
);

Parameters

pTimeStart
[out] Pointer to the retrieved beginning media time.
pTimeEnd
[out] Pointer to the retrieved ending media time.

Return Value

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.

IMediaSample::GetMediaType

IMediaSample Interface

Retrieves the media type of the IMediaSample object.

Syntax

HRESULT GetMediaType(
    AM_MEDIA_TYPE **ppMediaType
);

Parameters

ppMediaType
[in] Address of 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 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.

IMediaSample::GetPointer

IMediaSample Interface

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 an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

IMediaSample::GetSize

IMediaSample Interface

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

Syntax

HRESULT GetSize(void);

Return Value

Returns an HRESULT value that is the size.

Remarks

Although this is typed as returning an HRESULT value, it actually returns the size in bytes, not an error value.

IMediaSample::GetTime

IMediaSample Interface

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 the retrieved beginning stream time.
pTimeEnd
[out] Pointer to the retrieved ending stream time.

Return Value

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.

IMediaSample::IsDiscontinuity

IMediaSample Interface

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, or S_FALSE if not; otherwise, returns an HRESULT error value.

Remarks

Discontinuity occurs when a source filter seeks to a different place in the stream or when a filter drops samples for quality control.
While calling SetDiscontinuity with a value of TRUE (1) sets the discontinuity property, calling IsDiscontinuity on a discontinuous sample returns S_OK (0).

IMediaSample::IsPreroll

IMediaSample Interface

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, or S_FALSE if not; otherwise, returns an HRESULT error value.
While calling SetPreroll with a value of TRUE (1) sets the preroll property, calling IsPreroll on a preroll sample returns S_OK (0).

IMediaSample::IsSyncPoint

IMediaSample Interface

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

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.
While calling SetSyncPoint with a value of TRUE (1) sets the synchronization point, calling IsSyncPoint on a synchronization point sample returns S_OK (0).

IMediaSample::SetActualDataLength

IMediaSample Interface

Sets the sample's data length.

Syntax

HRESULT SetActualDataLength(
    long lLen
);

Parameters

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

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

IMediaSample::SetDiscontinuity

IMediaSample Interface

Sets the discontinuity property.

Syntax

HRESULT SetDiscontinuity(
    BOOL bIsDiscontinuity
);

Parameters

bIsDiscontinuity
[in] Value specifying discontinuity; set to TRUE to specify the media sample as discontinuous with the previous sample.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

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.
While calling SetDiscontinuity with a value of TRUE (1) sets the discontinuity property, calling IsDiscontinuity on a discontinuous sample returns S_OK (0).

IMediaSample::SetMediaTime

IMediaSample Interface

Sets the media time stamps 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 an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

To reset the time, use this method with both pTimeStart and pTimeEnd set to NULL. This will cause IMediaSample::GetMediaTime to return an error.

IMediaSample::SetMediaType

IMediaSample Interface

Sets the media type for the IMediaSample 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 that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

This method allows for limited in-band format changes.

IMediaSample::SetPreroll

IMediaSample Interface

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; otherwise, set to FALSE.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

Preroll samples are samples that are processed but not displayed, and are located in the media stream before the displayable samples.
While calling SetPreroll with a value of TRUE (1) sets the preroll property, calling IsPreroll on a preroll sample returns S_OK (0).

IMediaSample::SetSyncPoint

IMediaSample Interface

Sets or unsets the beginning of this sample is a synchronization point.

Syntax

HRESULT SetSyncPoint(
    BOOL bIsSyncPoint
);

Parameters

bIsSyncPoint
[in] Value specifying whether the sample is a synchronization point. Set to TRUE to specify the sample as a synchronization point; otherwise, set to FALSE.

Return Value

Returns S_OK if the sample was successfully set or unset as a synchronization point.

Remarks

A filter can begin a stream at any synchronization point. If AM_MEDIA_TYPE.bTemporalCompression is false then all samples are sync points.
While calling SetSyncPoint with a value of TRUE (1) sets the synchronization point, calling IsSyncPoint on a synchronization point sample returns S_OK (0).

IMediaSample::SetTime

IMediaSample Interface

Sets the stream time 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.
pTimeEnd
[in] Pointer to the stream time at which the sample ends.

Return Value

Returns an HRESULT value that depends on the implementation. HRESULT can be one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_POINTER Null pointer argument.
E_INVALIDARG Invalid argument.
E_NOTIMPL Method isn't supported.
S_OK or NOERROR Success.

Remarks

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.

E_FAIL	Failure.
E_POINTER	Null pointer argument.
E_INVALIDARG	Invalid argument.
E_NOTIMPL	Method isn't supported.
S_OK or NOERROR	Success.