The CImageAllocator class is inherited from the CBaseAllocator class, which allocates sample buffers in shared memory. The number, size, and alignment of blocks are determined when the connected output pin calls CImageAllocator::SetProperties (which implements IMemAllocator::SetProperties). The shared memory blocks are used in subsequent calls to the Microsoft® Win32® CreateDIBSection function. The output pin can then fill these buffers with data, and the buffers will be handed to GDI using BitBlt.
Protected Data Members
| Name | Description |
| m_pFilter | Owning filter of this object. |
| m_pMediaType | Current media type format. |
Member Functions
| Name | Description |
| Alloc | Allocates the samples through CreateDIBSection. |
| CheckSizes | Checks the allocator requirements. |
| CImageAllocator | Constructs a CImageAllocator object. |
| CreateDIB | Creates a device-independent bitmap (DIB). |
| Free | Releases and deletes the resources for any samples allocated. |
| NotifyMediaType | Notifies the allocator of the agreed media type. |
Overridable Member Functions
| Name | Description |
| CreateImageSample | Creates a sample. |
Implemented INonDelegatingUnknown Methods
| Name | Description |
| NonDelegatingAddRef | Increments the reference count for an interface. |
| NonDelegatingRelease | Decrements the reference count for an interface. |
Implemented IMemAllocator Methods
| Name | Description |
| SetProperties | Specifies the buffering requirements for the allocator. |
Creates image samples based around CreateDIBSection.
HRESULT Alloc( );
Returns an HRESULT value.
A filter defines the size and number of buffers required through the CImageAllocator::SetProperties member function. The base allocator class that this allocator derives from calls this internal virtual member function when it wants the memory actually committed. For each sample it wants to create, this allocator will create a DIBSECTION object for it (through the Microsoft Win32 CreateDIBSection function). With the information it gets from that call, it will call the virtual CreateImageSample member function, passing in the buffer pointer and length. After successfully creating an image sample, it will then initialize it with the DIBSECTION structure, among other information.
This is a protected member function.
Internal member function that checks the required buffering properties.
HRESULT CheckSizes(
ALLOCATOR_PROPERTIES *pRequest
);
Returns an HRESULT value.
The image allocator uses the Microsoft Win32 CreateDIBSection function to allocate its samples. That function accepts as input a pointer to a BITMAPINFO structure that describes the bitmap required. Because the size of the bitmap is therefore fixed according to the BITMAPINFO structure for the video, requests to the allocator for a buffer larger than that will not be granted. This member function, therefore, adjusts the requested size so that it is no larger than the size of the bitmap. If the requested size is smaller than the bitmap size, it returns E_INVALIDARG.
This is a protected member function.
Constructs a CImageAllocator object.
CImageAllocator(
CBaseFilter *pFilter,
TCHAR *pName,
HRESULT *phr
);
No return value.
The CImageAllocator, CImageSample, and CDrawImage classes are all tightly associated. The buffers that the image allocator creates are made using the Microsoft Win32 CreateDIBSection function. The allocator then creates its own samples (based on the CImageSample class). The image samples are initialized with the buffer pointer and its length. The sample is also passed in a structure (a DIBDATA structure) that holds a number of pieces of information obtained from the CreateDIBSection call.
These samples can then be passed to the draw object. The draw object knows the private format of the samples and how to get back the DIBDATA structure from them. Once it has obtained that information, it can pass a bitmap handle that is stored in the DIBDATA structure down into GDI when it draws the image that the sample contains. By using the bitmap handle from the sample in the drawing, rather than just the buffer pointer (which is the alternative if the sample is not a CImageSample), it gets a modest performance improvement.
This is a protected member function.
Calls the Win32 CreateDIBSection function to create a device-independent bitmap (DIB).
HRESULT CreateDIB(
LONG InSize,
DIBDATA &DibData
);
Returns an HRESULT value.
This is a protected member function.
Creates a CImageSample object.
virtual CImageSample *CreateImageSample(
LPBYTE pData,
LONG Length
);
Returns a new CImageSample sample object.
This virtual member function creates the actual sample for the allocator. It is passed the data buffer and its length to store. When the sample is subsequently asked for the buffer (through IMediaSample::GetPointer), this is the pointer it will return. The primary reason for having this split out into a separate virtual member function is so that derived classes from CImageAllocator can also derive classes from CImageSample and have a place to create them.
This is a protected member function.
Deletes the samples and frees their resources.
void Free( );
No return value.
The base allocator calls this internal virtual member function when it wants to decommit the allocator.
This is a protected member function.
Increments the reference count for the owning filter.
HRESULT NonDelegatingAddRef( );
Returns an HRESULT value.
An allocator is conceptually a separate object from the filter that creates it. However, the image allocator is dependent on the filter that created it to supply it with additional information (such as the media type that it connected with). Therefore, although the allocator looks after its own NonDelegatingQueryInterface function, it delegates all reference counting to the owning filter. So, when the allocator is subject to its NonDelegatingAddRef function, for example, it is the filter that owns the allocator that will actually be reference counted.
Decrements the reference count for the owning filter.
HRESULT NonDelegatingRelease( );
Returns an HRESULT value.
An allocator is conceptually a separate object from the filter that creates it. However, the image allocator is dependent on the filter that created it to supply it with additional information (such as the media type that it connected with). Therefore, although the allocator looks after its own NonDelegatingQueryInterface function, it delegates all reference counting to the owning filter. So when the allocator is released, for example, it is the filter that owns the allocator that will actually be released by the NonDelegatingRelease function.
Passes the media type from a filter to the allocator.
void NotifyMediaType(
CMediaType *pMediaType
);
No return value.
The buffers that the image allocator creates are based around CreateDIBSection, which must be told what sort of bitmap the filter requires it to create. The filter does this by calling this member function on the allocator. A filter will normally call this member function after agreeing on a media type during a pin connection. The media type passed to this member function is a pointer; the allocator stores this pointer (not a copy) of the media type it points to (for performance reasons, copying media types is relatively slow). Therefore, the filter that calls this member function should ensure that the media type is always valid until the media type is next set on the allocator (or is called with a NULL type).
Determines the size, number, and alignment of blocks.
HRESULT SetProperties(
ALLOCATOR_PROPERTIES * pRequest,
ALLOCATOR_PROPERTIES * pActual
);
Returns an HRESULT value.
The pRequest parameter is filled in by the caller with the requested values for the count, number, and alignment as specified by the ALLOCATOR_PROPERTIES structure. The pActual parameter is filled in by the allocator with the closest values that it can provide for the request. This member function cannot be called unless the allocator has been decommitted by using the IMemAllocator::Decommit method.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.