Microsoft DirectX 8.0 |
Delivers media data to an input pin. Input pins expose this interface if they use the IMemAllocator interface to allocate buffers. When an output pin connects to an input pin, the output pin uses this interface to negotiate allocator requirements and deliver samples to the input pin.
Applications typically do use this interface.
Filter developers: The CBaseInputPin class implements this interface.
Methods in Vtable Order
IUnknown methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IMemInputPin methods Description GetAllocator Retrieves the memory allocator proposed by this pin. NotifyAllocator Specifies an allocator for the connection. GetAllocatorRequirements Retrieves allocator properties that are requested by the input pin. Receive Receives the next media sample in the stream. ReceiveMultiple Receives multiple samples in the stream. ReceiveCanBlock Determines whether calls to the Receive method might block.
Retrieves the memory allocator proposed by this pin.
Syntax
HRESULT GetAllocator( IMemAllocator **ppAllocator );
Parameters
- ppAllocator
- [out] Address of a variable that receives a pointer to the allocator's IMemAllocator interface.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success. VFW_E_NO_ALLOCATOR No allocator is available.
Remarks
When an output pin connects to an input pin, it negotiates with the input pin to decide on a memory allocator. The output pin calls this method to retrieve the input pin's proposed allocator. It calls the NotifyAllocator method to specify which allocator it selected.
If this method succeeds, the IMemAllocator interface has an outstanding reference count. Be sure to release it when you are done.
Retrieves the allocator properties requested by the input pin.
Syntax
HRESULT GetAllocatorRequirements( ALLOCATOR_PROPERTIES *pProps );
Parameters
- pProps
- [in] Pointer to an ALLOCATOR_PROPERTIES structure, which is filled in with the requirements.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success E_NOTIMPL Not implemented E_POINTER NULL pointer argument
Remarks
When an output pin initializes a memory allocator, it can call this method to determine whether the input pin has any buffer requirements. The input pin is not required to implement this method. If the filter has specific alignment or prefix requirements, it should implement this method.
Specifies an allocator for the connection.
Syntax
HRESULT NotifyAllocator( IMemAllocator *pAllocator, BOOL bReadOnly );
Parameters
- pAllocator
- [in] Pointer to the allocator's IMemAllocator interface.
- bReadOnly
- [out] Flag that specifies whether samples from this allocator are read-only. If TRUE, samples are read-only.
Return Value
Returns S_OK if successful, or an HRESULT value indicating the cause of the error.
Remarks
During the pin connection, the output pin chooses an allocator and calls this method to notify the input pin. The output pin might use the allocator that the input pin proposed in the IMemInputPin::GetAllocator method, or it might provide its own allocator.
If the bReadOnly parameter is TRUE, all samples in the allocator are read-only. The filter must copy them to modify the data.
Receives the next media sample in the stream.
Syntax
HRESULT Receive( IMediaSample *pSample );
Parameters
- pSample
- [in] Pointer to the sample's IMediaSample interface.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success. S_FALSE Pin is currently flushing; sample was rejected. E_POINTER NULL pointer argument. VFW_E_INVALIDMEDIATYPE Invalid media type. VFW_E_RUNTIME_ERROR A run-time error occurred. VFW_E_WRONG_STATE The pin is stopped.
Remarks
This method is synchronous and possibly blocking. The pin does one of the following:
- Rejects the sample.
- Returns immediately and processes the sample in a worker thread.
- Processes the sample before returning.
In the last case, the method might block indefinitely. If this might happen, the ReceiveCanBlock method returns S_OK.
If the pin uses a worker thread to process the sample, it holds a reference count on the sample. In any case, the output pin cannot directly re-use this sample. It must call the IMemAllocator::GetBuffer method to obtain a new sample.
Determines whether calls to the Receive method might block.
Syntax
HRESULT ReceiveCanBlock(void);
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_FALSE The pin will not block on a call to Receive S_OK The pin might block on a call to Receive.
Remarks
If this method returns S_FALSE, calls to the Receive method are guaranteed not to block. Otherwise, they might block. An upstream filter can use this method to determine its threading strategy. If calls to Receive can block, the upstream filter might decide to use a worker thread that buffers data.
Receives multiple samples in the stream.
Syntax
HRESULT ReceiveMultiple( IMediaSample **pSamples, long nSamples, long *nSamplesProcessed );
Parameters
- pSamples
- [in] Address of an array of IMediaSample pointers, of size nSamples.
- nSamples
- [in] Number of samples to process.
- nSamplesProcessed
- [out] Pointer to a variable that receives the number of samples that were processed.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success. S_FALSE Pin is currently flushing; sample was rejected. E_POINTER NULL pointer argument. VFW_E_INVALIDMEDIATYPE Invalid media type. VFW_E_RUNTIME_ERROR A run-time error occurred. VFW_E_WRONG_STATE The pin is stopped.
Remarks
This method behaves like the Receive method, but receives an array of samples.