Microsoft DirectX 8.0

IMemInputPin Interface

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 methodsDescription
QueryInterface Retrieves pointers to supported interfaces.
AddRef Increments the reference count.
Release Decrements the reference count.
IMemInputPin methodsDescription
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.

IMemInputPin::GetAllocator

IMemInputPin Interface

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_OKSuccess.
VFW_E_NO_ALLOCATORNo 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.

IMemInputPin::GetAllocatorRequirements

IMemInputPin Interface

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_OKSuccess
E_NOTIMPLNot implemented
E_POINTERNULL 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.

IMemInputPin::NotifyAllocator

IMemInputPin Interface

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.

IMemInputPin::Receive

IMemInputPin Interface

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_OKSuccess.
S_FALSEPin is currently flushing; sample was rejected.
E_POINTERNULL pointer argument.
VFW_E_INVALIDMEDIATYPEInvalid media type.
VFW_E_RUNTIME_ERRORA run-time error occurred.
VFW_E_WRONG_STATEThe pin is stopped.

Remarks

This method is synchronous and possibly blocking. The pin does one of the following:

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.

IMemInputPin::ReceiveCanBlock

IMemInputPin Interface

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.

IMemInputPin::ReceiveMultiple

IMemInputPin Interface

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_OKSuccess.
S_FALSEPin is currently flushing; sample was rejected.
E_POINTERNULL pointer argument.
VFW_E_INVALIDMEDIATYPEInvalid media type.
VFW_E_RUNTIME_ERRORA run-time error occurred.
VFW_E_WRONG_STATEThe pin is stopped.

Remarks

This method behaves like the Receive method, but receives an array of samples.