CImageAllocator Class
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
m_pFilter Owning filter of this object. m_pMediaType Current media type format.
Member Functions
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
CreateImageSample Creates a sample.
Implemented INonDelegatingUnknown Methods
NonDelegatingAddRef Increments the reference count for an interface. NonDelegatingRelease Decrements the reference count for an interface.
Implemented IMemAllocator Methods
SetProperties Specifies the buffering requirements for the allocator.
CImageAllocator::Alloc
CImageAllocator Class
Creates image samples based around CreateDIBSection.
Syntax
HRESULT Alloc(void);
Return Value
Returns an HRESULT value.
Remarks
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.
CImageAllocator::CheckSizes
CImageAllocator Class
Internal member function that checks the required buffering properties.
Syntax
HRESULT CheckSizes(
ALLOCATOR_PROPERTIES *pRequest
);
Parameters
- pRequest
- Pointer to requested allocator properties.
Return Value
Returns an HRESULT value.
Remarks
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.
CImageAllocator::CImageAllocator
CImageAllocator Class
Constructs a CImageAllocator object.
Syntax
CImageAllocator(
CBaseFilter *pFilter,
TCHAR *pName,
HRESULT *phr
);
Parameters
- pFilter
- Pointer to the owning filter object.
- pName
- Pointer to a debug-only string description.
- phr
- Pointer to a COM return code.
Return Value
No return value.
Remarks
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.
CImageAllocator::CreateDIB
CImageAllocator Class
Calls the Win32 CreateDIBSection function to create a device-independent bitmap (DIB).
Syntax
HRESULT CreateDIB(
LONG InSize,
DIBDATA &DibData
);
Parameters
- InSize
- Size of the bitmap required.
- DibData
- Structure to fill out with details.
Return Value
Returns an HRESULT value.
Remarks
This is a protected member function.
CImageAllocator::CreateImageSample
CImageAllocator Class
Creates a CImageSample object.
Syntax
virtual CImageSample *CreateImageSample(
LPBYTE pData,
LONG Length
);
Parameters
- pData
- Pointer to the data buffer the sample looks after.
- Length
- Associated length of the buffer.
Return Value
Returns a new CImageSample sample object.
Remarks
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.
CImageAllocator::Free
CImageAllocator Class
Deletes the samples and frees their resources.
Syntax
void Free(void);
Return Value
No return value.
Remarks
The base allocator calls this internal virtual member function when it wants to decommit the allocator.
This is a protected member function.
CImageAllocator::NonDelegatingAddRef
CImageAllocator Class
Increments the reference count for the owning filter.
Syntax
HRESULT NonDelegatingAddRef(void);
Return Value
Returns an HRESULT value.
Remarks
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.
CImageAllocator::NonDelegatingRelease
CImageAllocator Class
Decrements the reference count for the owning filter.
Syntax
HRESULT NonDelegatingRelease(void);
Return Value
Returns an HRESULT value.
Remarks
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.
CImageAllocator::NotifyMediaType
CImageAllocator Class
Passes the media type from a filter to the allocator.
Syntax
void NotifyMediaType(
CMediaType *pMediaType
);
Parameters
- pMediaType
- Pointer to the media type the filter established.
Return Value
No return value.
Remarks
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 usually 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).
CImageAllocator::SetProperties
CImageAllocator Class
Determines the size, number, and alignment of blocks.
Syntax
HRESULT SetProperties(
ALLOCATOR_PROPERTIES *pRequest,
ALLOCATOR_PROPERTIES *pActual
);
Parameters
- pRequest
- Pointer to requested allocator properties.
- pActual
- Pointer to allocator properties actually set.
Return Value
Returns an HRESULT value.
Remarks
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.
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.