Microsoft DirectX 8.0

IMediaSample Interface

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 methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IMediaSample methodsDescription
GetPointerRetrieves a read/write pointer to this buffer's memory.
GetSizeRetrieves the size of the buffer.
GetTimeRetrieves the stream times at which this sample should begin and finish.
SetTimeSets the stream time when this sample should begin and finish.
IsSyncPointDetermines if the beginning of this sample is a synchronization point.
SetSyncPointSpecifies whether the beginning of this sample is a synchronization point.
IsPrerollDetermines if this sample is a preroll sample.
SetPrerollSpecifies whether this sample is a preroll sample.
GetActualDataLengthRetrieves the length of the valid data in the buffer.
SetActualDataLengthSets the length of the valid data in the buffer.
GetMediaTypeRetrieves the media type, if the media type differs from the previous sample.
SetMediaTypeSets the media type for the sample.
IsDiscontinuityDetermines if this sample represents a break in the data stream.
SetDiscontinuitySpecifies whether this sample represents a break in the data stream.
GetMediaTimeRetrieves the media times for this sample.
SetMediaTimeSets the media times for this sample.

IMediaSample::GetActualDataLength

IMediaSample Interface

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.

IMediaSample::GetMediaTime

IMediaSample Interface

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_OKSuccess.
VFW_E_MEDIA_TIME_NOT_SETMedia times are not set on this sample.

Remarks

For more information about media times, see Time and Clocks in DirectShow.

IMediaSample::GetMediaType

IMediaSample Interface

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_FALSEThe media type has not changed from the previous sample.
S_OKSuccess.
E_OUTOFMEMORYInsufficient 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

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 S_OK if successful, or an HRESULT value indicating the cause of the error.

IMediaSample::GetSize

IMediaSample Interface

Retrieves the size of the buffer.

Syntax

long GetSize(void);

Return Value

Returns the size of the buffer, in bytes.

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 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_OKSuccess. The sample has valid start and stop times.
VFW_S_NO_STOP_TIMEThe sample has a valid start time, but no stop time.
VFW_E_SAMPLE_TIME_NOT_SETThe sample is not time-stamped.

Remarks

For more information about stream times, see Time and Clocks in DirectShow.

IMediaSample::IsDiscontinuity

IMediaSample Interface

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

IMediaSample Interface

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

IMediaSample Interface

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

IMediaSample Interface

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_OKSuccess.
VFW_E_BUFFER_OVERFLOW.Length specified in lLen is larger than the buffer size.

IMediaSample::SetDiscontinuity

IMediaSample Interface

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::IsDiscontinuity

IMediaSample::SetMediaTime

IMediaSample Interface

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

IMediaSample Interface

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_OKSuccess
E_OUTOFMEMORYInsufficient 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

IMediaSample Interface

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::IsPreroll

IMediaSample::SetSyncPoint

IMediaSample Interface

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::IsSyncPoint

IMediaSample::SetTime

IMediaSample Interface

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.