Microsoft DirectX 8.0

IAMMediaTypeSample Interface

This interface contains methods for manipulating stream samples with arbitrary media types. Call the IAMMediaTypeStream::CreateSample method to create a sample that exposes this interface.

This interface inherits from the IStreamSample interface.

The methods in this interface parallel those of the IMediaSample interface, although IAMMediaTypeSample contains a SetPointer method in addition to the GetPointer method.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterfaceRetrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IStreamSample methodsDescription
GetMediaStreamRetrieves a pointer to the media stream object that created the current sample.
GetSampleTimesRetrieves the current sample's start and end times.
SetSampleTimesSets the current sample's start and end times.
UpdatePerforms a synchronous or an asynchronous update on the current sample.
CompletionStatusRetrieves the status of the current sample's latest asynchronous update. If the update isn't complete, you can force it to complete.
IAMMediaTypeSample methodsDescription
SetPointerSets the pointer to the media sample's memory buffer.
GetPointerRetrieves a read/write pointer to the buffer's memory.
GetSizeRetrieves the size of the buffer data area, in bytes.
GetTimeRetrieves the stream times at which this sample should start and stop.
SetTimeSets the stream times at which this sample should start and stop.
IsSyncPointDetermines if the beginning of a sample is a synchronization point.
SetSyncPointSpecifies whether the beginning of this sample is a synchronization point.
IsPrerollDetermines if this sample is part of the preroll.
SetPrerollSpecifies whether this is a preroll sample.
GetActualDataLengthRetrieves the data length of the sample, in bytes.
SetActualDataLengthSets the sample's data length.
GetMediaTypeRetrieves the media type of the sample.
SetMediaTypeSets the media type for the sample.
IsDiscontinuityDetermines if this sample represents a discontinuity in the data stream.
SetDiscontinuitySets the discontinuity property.
GetMediaTimeRetrieves the media time stamps for this sample.
SetMediaTimeSets the media time stamps for this sample.

IAMMediaTypeSample::GetActualDataLength

IAMMediaTypeSample Interface

Retrieves the data length of the sample, in bytes.

Syntax

long GetActualDataLength(void);

Return Value

Returns the data length of the sample, in bytes.

IAMMediaTypeSample::GetMediaTime

IAMMediaTypeSample Interface

Retrieves the media time stamps for the sample.

Syntax

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

Parameters

pTimeEnd
[out] Pointer to a variable that receives the media start time.
pTimeStart
[out] Pointer to a variable that receives the media stop time.

Return Value

Returns one of the following values.

S_OKSuccess.
VFW_E_MEDIA_TIME_NOT_SETNo media time stamp was set for this sample.

IAMMediaTypeSample::GetMediaType

IAMMediaTypeSample Interface

Retrieves the media type of the sample. If the format has not changed from the previous sample, the sample might not carry a media type.

Syntax

HRESULT GetMediaType(
    AM_MEDIA_TYPE **ppMediaType
);

Parameters

ppMediaType
Address of a pointer that receives an AM_MEDIA_TYPE structure.

Return Value

Returns one of the following values.

E_OUTOFMEMORYInsufficient memory.
S_FALSEThe format has not changed from the previous sample.
S_OKSuccess.

IAMMediaTypeSample::GetPointer

IAMMediaTypeSample Interface

Retrieves a read/write pointer to the buffer's memory.

Syntax

HRESULT GetPointer(
    BYTE **ppBuffer
);

Parameters

ppBuffer
[out] Address of a pointer to the buffer.

Return Value

Returns S_OK.

IAMMediaTypeSample::GetSize

IAMMediaTypeSample Interface

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

Syntax

long GetSize(void);

Return Value

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

IAMMediaTypeSample::GetTime

IAMMediaTypeSample Interface

Retrieves the stream times at which the sample should start and stop.

Syntax

HRESULT GetTime(
    REFERENCE_TIME *pTimeStart,
    REFERENCE_TIME *pTimeEnd
);

Parameters

pTimeStart
[out] Pointer to a variable that receives the start time.
pTimeEnd
[out] Pointer to a variable that receives the stop time. If the sample has no stop time, the value is set to the start time plus one.

Return Value

Returns one of the following values.

S_OKSuccess.
VFW_E_SAMPLE_TIME_NOT_SETThe sample does not have any time stamps.
VFW_S_NO_STOP_TIMEThe sample has a valid start time but no stop time.

IAMMediaTypeSample::IsDiscontinuity

IAMMediaTypeSample Interface

Determines if this sample represents a discontinuity in the data stream.

Syntax

HRESULT IsDiscontinuity(void);

Return Value

Returns S_OK if this sample is a discontinuity, or S_FALSE otherwise.

IAMMediaTypeSample::IsPreroll

IAMMediaTypeSample Interface

Determines if this sample is part of the preroll. A preroll sample should not be displayed.

Syntax

HRESULT IsPreroll(void);

Return Value

Returns S_OK if the sample is a preroll sample, or S_FALSE otherwise.

IAMMediaTypeSample::IsSyncPoint

IAMMediaTypeSample Interface

Determines if the beginning of a sample is a synchronization point.

Syntax

HRESULT IsSyncPoint(void);

Return Value

Returns S_OK if the beginning of the sample is a synchronization point, or S_FALSE otherwise.

IAMMediaTypeSample::SetActualDataLength

IAMMediaTypeSample Interface

Sets the sample's data length.

Syntax

HRESULT SetActualDataLength(
    long lActual
);

Parameters

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

Return Value

Returns one of the following values.
S_OKSuccess.
VFW_E_BUFFER_OVERFLOWThe buffer is not big enough.

IAMMediaTypeSample::SetDiscontinuity

IAMMediaTypeSample Interface

Sets the discontinuity property.

Syntax

HRESULT SetDiscontinuity(
    BOOL bDiscontinuity
);

Parameters

bDiscontinuity
Value that specifies whether this sample is a discontinuity. If the sample is discontinuous with the previous sample, set the value to TRUE. Otherwise, set the value to FALSE.

Return Value

Returns S_OK.

IAMMediaTypeSample::SetMediaTime

IAMMediaTypeSample Interface

Sets the media time stamps for this sample.

Syntax

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

Parameters

pTimeEnd
[in] Pointer to a variable that contains the media start time.
pTimeStart
[in] Pointer to a variable that contains the media stop time.

Return Value

Returns S_OK.

IAMMediaTypeSample::SetMediaType

IAMMediaTypeSample 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 describes the media type.

Return Value

Returns one of the following values.

E_OUTOFMEMORYInsufficient memory.
S_OKSuccess.

IAMMediaTypeSample::SetPointer

IAMMediaTypeSample Interface

Sets the pointer to the media sample's memory buffer.

Syntax

HRESULT SetPointer(
    BYTE *pBuffer,
    long lSize
);

Parameters

pBuffer
[in] Pointer to a memory buffer allocated by the caller, or NULL.
lSize
[in] Size of the buffer, in bytes.

Return Value

Returns one of the following HRESULT values.

S_OKSuccess.
E_OUTOFMEMORYInsufficient memory.

Remarks

If the value of the pBuffer parameter is NULL, the method allocates a memory block, with a size in bytes equal to the value of the lSize parameter. There is no guarantee that the memory has been initialized.

IAMMediaTypeSample::SetPreroll

IAMMediaTypeSample Interface

Specifies whether this is a preroll sample. A preroll sample should not be displayed.

Syntax

HRESULT SetPreroll(
    BOOL bIsPreroll
);

Parameters

bIsPreroll
Boolean value that specifies whether the sample is a preroll sample. If TRUE, it is for preroll and should not be displayed.

Return Value

Returns S_OK.

IAMMediaTypeSample::SetSyncPoint

IAMMediaTypeSample Interface

Specifies whether the beginning of this sample is a synchronization point.

Syntax

HRESULT SetSyncPoint(
    BOOL bIsSyncPoint
);

Parameters

bIsSyncPoint
Boolean value that specifies whether the beginning of this sample is a synchronization point. If TRUE, the beginning of the sample is a synchronization point.

Return Value

Returns S_OK.

IAMMediaTypeSample::SetTime

IAMMediaTypeSample Interface

Sets the stream times at which the sample should start and stop.

Syntax

HRESULT SetTime(
    REFERENCE_TIME *pTimeStart,
    REFERENCE_TIME *pTimeEnd
);

Parameters

pTimeStart
[in] Pointer to a variable that contains the start time.
pTimeEnd
[in] Pointer to a variable that contains the stop time.

Return Value

Returns S_OK.