Microsoft DirectX 8.0 |
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 methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. ISampleGrabber methods Description SetOneShot Specifies whether the filter should stop the graph after receiving one sample. SetMediaType Specifies the media type for the connection on the Sample Grabber's input pin. GetConnectedMediaType Retrieves the media type for the connection on the Sample Grabber's input pin. SetBufferSamples Specifies whether to copy sample data into a buffer as it goes through the filter. GetCurrentBuffer Retrieves a copy of the sample that the filter received most recently. GetCurrentSample Not currently implemented. SetCallback Specifies a callback method to call on incoming samples.
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_POINTER NULL pointer argument. S_OK Success. VFW_E_NOT_CONNECTED Filter is not connected.
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_INVALIDARG Samples are not being buffered. E_POINTER NULL pointer argument. S_OK Success. VFW_E_NOT_CONNECTED Filter is not connected. VFW_E_WRONG_STATE The filter is in the wrong state.
Remarks
To activate buffering, call SetBufferSamples with a value of TRUE.
Not currently implemented.
Syntax
HRESULT GetCurrentSample( IMediaSample **ppSample );
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.
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.
0 Call the ISampleGrabberCB::SampleCB method. 1 Call the ISampleGrabberCB::BufferCB method.
Return Value
Returns one of the following values.
E_INVALIDARG Samples are not being buffered. S_OK Success.
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.
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.
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.