Microsoft DirectX 8.0

IMediaSample2 Interface

Sets and retrieves properties on media samples. This interface inherits the IMediaSample interface. The IMediaSample interface requires separate method calls for each sample property. The IMediaSample2 interface adds methods that set or retrieve multiple properties at once.

Media samples are not guaranteed to support IMediaSample2. However, if an allocator does create samples that support IMediaSample2, all of the samples it generates must support the 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.
IMediaSample2 methodsDescription
GetProperties Retrieves the properties of a media sample.
SetProperties Sets the properties of a media sample.

IMediaSample2::GetProperties

IMediaSample2 Interface

Retrieves the properties of a media sample.

Syntax

HRESULT GetProperties(
    DWORD cbProperties,
    BYTE *pbProperties
);

Parameters

cbProperties
[in] Length of property data to retrieve, in bytes.
pbProperties
[out] Pointer to a buffer of size cbProperties.

Return Value

Returns an HRESULT value. Possible values include the following.

S_OKSuccess.
E_POINTERNULL pointer argument.

Remarks

The retrieved data conforms to the format of the AM_SAMPLE2_PROPERTIES structure. You can retrieve a subset of the sample properties by setting cbProperties to a value less than the size of the AM_SAMPLE2_PROPERTIES structure.

For efficiency, the pMediaType member returned in AM_SAMPLE2_PROPERTIES is a pointer to the data stored in the media sample, not a copy of that data. The pointer may become invalid after the sample is passed to another filter, or after the input pin's IMemInputPin::Receive method has completed. Also, do not free the pointer or delete the media type.

IMediaSample2::SetProperties

IMediaSample2 Interface

Sets the properties of a media sample.

Syntax

HRESULT SetProperties(
    DWORD cbProperties,
    const BYTE *pbProperties
);

Parameters

cbProperties
[in] Length of property data to set, in bytes.
pbProperties
[in] Pointer to a buffer of size cbProperties.

Return Value

Returns an HRESULT value. Possible values include the following.
S_OKSuccess.
E_INVALIDARGInvalid argument.
E_OUTOFMEMORYInsufficient memory.
E_POINTERNULL pointer argument.

Remarks

The data contained in pbProperties must conform to the format of the AM_SAMPLE2_PROPERTIES structure. You can specify a subset of the sample properties by setting cbProperties to a value less than the size of the AM_SAMPLE2_PROPERTIES structure.