Microsoft DirectX 8.0 |
Allocates media samples, for moving data between pins.
This interface is used by pins that share allocators, when the input pin exposes the IMemInputPin interface. The pins negotiate which pin will provide the allocator. The allocator is used to allocate memory buffers, retrieve empty buffers, and release buffers. Not every filter creates its own allocator, so one allocator might be used by several filters. For more information, see Connection Model.
Applications typically do not use this interface.
To use an allocator, perform the following steps:
Methods in Vtable Order
IUnknown methods Description QueryInterface Retrieves pointers to supported interfaces. AddRef Increments the reference count. Release Decrements the reference count. IMemAllocator methods Description SetProperties Specifies the number of buffers to allocate and the size of each buffer. GetProperties Retrieves the number of buffers that the allocator will create, and the buffer properties. Commit Allocates the buffer memory. Decommit Releases the memory for the buffers. GetBuffer Retrieves a media sample that contains an empty buffer. ReleaseBuffer Releases a media sample.
Allocates the buffer memory.
Syntax
HRESULT Commit(void);
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success. E_OUTOFMEMORY Insufficient memory. VFW_E_SIZENOTSET Buffer requirements were not set.
Remarks
Before calling this method, call the IMemAllocator::SetProperties method to specify the buffer requirements.
You must call this method before calling the IMemAllocator::GetBuffer method.
Releases the memory for the buffers.
Syntax
HRESULT Decommit(void);
Return Value
Returns S_OK if successful, or an HRESULT value indicating the cause of the error.
Remarks
Any threads waiting in the IMemAllocator::GetBuffer method return with an error. Further calls to GetBuffer fail, until the IMemAllocator::Commit method is called.
Retrieves a media sample that contains an empty buffer.
Syntax
HRESULT GetBuffer( IMediaSample **ppBuffer, REFERENCE_TIME *pStartTime, REFERENCE_TIME *pEndTime, DWORD dwFlags );
Parameters
- ppBuffer
- [out] Address of a variable that receives a pointer to the buffer's IMediaSample interface.
- pStartTime
- [in] Pointer to the start time of the sample, or NULL.
- pEndTime
- [in] Pointer to the ending time of the sample, or NULL.
- dwFlags
- [in] Bitwise combination of zero or more of the following flags.
- AM_GBF_NOTASYNCPOINT: This sample is not a synchronization point. Dynamic format changes are not allowed on this sample.
- AM_GBF_PREVFRAMESKIPPED: This sample is the first after a discontinuity. (Only the video renderer uses this flag.)
- AM_GBF_NOWAIT: Do not wait for a buffer to become available.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success. VFW_E_NOT_COMMITTED Allocator is decommitted. VFW_E_TIMEOUT Timed out.
Remarks
By default, this method blocks until a free sample is available or the allocator is decommitted. If the caller specifies the AM_GBF_NOWAIT flag and no sample is available, the allocator can return immediately with a return value of VFW_E_TIMEOUT. However, allocators are not required to support this flag.
The sample returned in ppBuffer has a valid buffer pointer. The caller is responsible for setting any other properties on the sample, such as the time stamps, the media times, or the sync-point property. (For more information, see IMediaSample.)
The pStartTime and pEndTime parameters are not applied to the sample. The allocator might use these values to determine which buffer it retrieves. For example, the Video Renderer filter uses these values to synchronize switching between Microsoft® DirectDraw® surfaces. To set the time stamp on the sample, call the IMediaSample::SetTime method.
You must call the IMemAllocator::Commit method before calling this method. This method fails after the IMemAllocator::Decommit method is called. If the method succeeds, the IMediaSample interface that it returns has an outstanding reference count. Be sure to release the interface when you are done using it.
Retrieves the number of buffers that the allocator will create, and the buffer properties.
Syntax
HRESULT GetProperties( ALLOCATOR_PROPERTIES *pProps );
Parameters
- pProps
- [out] Pointer to an ALLOCATOR_PROPERTIES structure that receives the allocator properties.
Return Value
Returns S_OK if successful, or an HRESULT value indicating the cause of the error.
Remarks
Calls to this method might not succeed until the IMemAllocator::Commit method is called.
Releases a media sample.
Syntax
HRESULT ReleaseBuffer( IMediaSample *pBuffer );
Parameters
- pBuffer
- [in] Pointer to the media sample's IMediaSample interface.
Return Value
Returns S_OK if successful, or an HRESULT value indicating the cause of the error.
Remarks
When a media sample's reference count reaches zero, it calls this method with itself as the pBuffer parameter. This method releases the sample back to the allocator's list of available samples.
Specifies the number of buffers to allocate and the size of each buffer.
Syntax
HRESULT SetProperties( ALLOCATOR_PROPERTIES *pRequest, ALLOCATOR_PROPERTIES *pActual );
Parameters
- pRequest
- Pointer to an ALLOCATOR_PROPERTIES structure that contains the buffer requirements.
- pActual
- Pointer to an ALLOCATOR_PROPERTIES structure that receives the actual buffer properties.
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success. E_POINTER NULL pointer argument. VFW_E_ALREADY_COMMITTED Cannot change allocated memory while the filter is active. VFW_E_BADALIGN An invalid alignment was specified. VFW_E_BUFFERS_OUTSTANDING One or more buffers are still active.
Remarks
This method specifies the buffer requirements, but does not allocate any buffers. Call the IMemAllocator::Commit method to allocate buffers.
The caller allocates two ALLOCATOR_PROPERTIES structures. The pRequest parameter contains the caller's buffer requirements, including the number of buffers and the size of each buffer. When the method returns, the pActual parameter contains the actual buffer properties, as set by the allocator.
When this method is called, the allocator must not be committed or have outstanding buffers.