Microsoft DirectX 8.0

ISampleGrabber Interface

This interface provides methods for retrieving individual media samples as they move through the filter graph.

The Sample Grabber filter exposes this interface. Applications can call methods on this interface to retrieve media samples. For more information, see Grabbing Media Samples.

Requirements

Requires Qedit.h.

Methods in Vtable Order

IUnknown methodsDescription
QueryInterfaceRetrieves pointers to supported interfaces.
AddRefIncrements the reference count.
ReleaseDecrements the reference count.
ISampleGrabber methodsDescription
SetOneShotSpecifies whether the filter should stop the graph after receiving one sample.
SetMediaTypeSpecifies the media type for the connection on the Sample Grabber's input pin.
GetConnectedMediaTypeRetrieves the media type for the connection on the Sample Grabber's input pin.
SetBufferSamplesSpecifies whether to copy sample data into a buffer as it goes through the filter.
GetCurrentBufferRetrieves a copy of the sample that the filter received most recently.
GetCurrentSampleNot currently implemented.
SetCallbackSpecifies a callback method to call on incoming samples.

ISampleGrabber::GetConnectedMediaType

ISampleGrabber Interface

Retrieves the media type for the connection on the Sample Grabber's input pin.

Syntax

HRESULT GetConnectedMediaType( 
    AM_MEDIA_TYPE *pType 
);

Parameters

pType
Pointer to a variable that receives an AM_MEDIA_TYPE structure.

Return Value

Returns one of the following values.

E_POINTERNULL pointer argument.
S_OKSuccess.
VFW_E_NOT_CONNECTEDFilter is not connected.

ISampleGrabber::GetCurrentBuffer

ISampleGrabber Interface

Retrieves a copy of the buffer associated with the most recent sample.

Syntax

HRESULT GetCurrentBuffer(
    long *pBufferSize,
    long *pBuffer
);

Parameters

pBufferSize
[in, out] Pointer to the size of the buffer. If pBuffer is NULL, this parameter receives the required size. If pBuffer is not NULL, this parameter specifies the buffer size.
pBuffer
[out] Pointer to a buffer to receive a copy of the sample, or NULL.

Return Value

Returns one of the following values.

E_INVALIDARGSamples are not being buffered.
E_POINTERNULL pointer argument.
S_OKSuccess.
VFW_E_NOT_CONNECTEDFilter is not connected.
VFW_E_WRONG_STATEThe filter is in the wrong state.

Remarks

To activate buffering, call SetBufferSamples with a value of TRUE.

ISampleGrabber::GetCurrentSample

ISampleGrabber Interface

Not currently implemented.

Syntax

HRESULT GetCurrentSample(	
    IMediaSample **ppSample
);

ISampleGrabber::SetBufferSamples

ISampleGrabber Interface

Specifies whether to copy sample data into a buffer as it goes through the filter.

Syntax

HRESULT SetBufferSamples(
    BOOL BufferThem
);

Parameters

BufferThem
Boolean value specifying whether to buffer sample data. If TRUE, the filter copies sample data into an internal buffer.

Return Value

Returns S_OK.

ISampleGrabber::SetCallback

ISampleGrabber Interface

Specifies a callback method to call on incoming samples.

Syntax

HRESULT SetCallback( 
    ISampleGrabberCB *pCallback, 
    long WhichMethodToCallback 
);

Parameters

pCallback
Pointer to an ISampleGrabberCB interface containing the callback method, or NULL to cancel the callback.
WhichMethodToCallback
Index specifying the callback method. Must be one of the following values.
0Call the ISampleGrabberCB::SampleCB method.
1Call the ISampleGrabberCB::BufferCB method.

Return Value

Returns one of the following values.

E_INVALIDARGSamples are not being buffered.
S_OKSuccess.

Remarks

If the sample is a Microsoft® DirectDraw® surface, the surface is locked during the callback. The Win16 lock (also called Win16Mutex) might be locked as well. Both of these locks create the potential for deadlock. If the callback thread waits for a thread that is trying to call a DirectDraw API, it can cause deadlock. In addition, if the Win16 lock is being held, deadlock can result if the callback holds a critical section or waits for another thread to complete any activity.

Therefore, the callback should not perform any actions with the potential to block, such as holding a critical section or waiting on another thread. Also, do not call any GDI or USER32.DLL APIs that might cause a window to move. For more information about the Win16 lock, see Knowledge Base article Q125867, Understanding Win16Mutex (http://support.microsoft.com/support/kb/articles/Q125/8/67.asp).

The data processing thread blocks until the callback method returns. If the callback does not return quickly, it can interfere with playback.

ISampleGrabber::SetMediaType

ISampleGrabber Interface

Specifies the media type for the connection on the Sample Grabber's input pin.

Syntax

HRESULT SetMediaType( 
    const AM_MEDIA_TYPE *pType 
);

Parameters

pType
Pointer to a variable of type AM_MEDIA_TYPE that specifies the media type. It is not necessary to set all the structure members. This parameter can specify just the major type; specify the major type and the subtype; or specify the major type, subtype, and format type. The other structure members are ignored.

Return Value

Returns S_OK.

Remarks

By default, the Sample Grabber has no preferred media type. To ensure that the Sample Grabber connects to the correct filter, call this method before rendering the graph.

ISampleGrabber::SetOneShot

ISampleGrabber Interface

Specifies whether the filter should stop the graph after receiving one sample.

Syntax

HRESULT SetOneShot(
    BOOL OneShot
);

Parameters

OneShot
Boolean value specifying whether the filter should stop the graph after receiving one sample. If TRUE, the filter stops upon receiving the first sample and signals EC_COMPLETE. If FALSE, the filter continues to run normally.

Return Value

Returns S_OK.

Remarks

You can retrieve a sample at a particular time by calling this method with a value of TRUE, seeking to the desired time, and running the graph.