Index
|
|
|
|
|
| |||
| |||
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
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. CImageAllocator Class
CImageAllocator::AllocCreates image samples based around CreateDIBSection.
HRESULT Alloc( );
Return Values
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 Class
CImageAllocator::CheckSizesInternal member function that checks the required buffering properties.
HRESULT CheckSizes(
ALLOCATOR_PROPERTIES *pRequest
);Parameters
- pRequest
- Requested allocator properties.
Return Values
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 Class
CImageAllocator::CImageAllocatorConstructs a CImageAllocator object.
CImageAllocator(
CBaseFilter *pFilter,
TCHAR *pName,
HRESULT *phr
);Parameters
- pFilter
- Owning filter object.
- pName
- Debug-only string description.
- phr
- COM return code.
Return Values
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 Class
CImageAllocator::CreateDIBCalls the Win32 CreateDIBSection function to create a device-independent bitmap (DIB).
HRESULT CreateDIB(
LONG InSize,
DIBDATA &DibData
);Parameters
- InSize
- Size of the bitmap required.
- DibData
- Structure to fill out with details.
Return Values
Returns an HRESULT value.
Remarks
This is a protected member function.
CImageAllocator Class
CImageAllocator::CreateImageSampleCreates a CImageSample object.
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 Values
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 Class
CImageAllocator::FreeDeletes the samples and frees their resources.
void Free( );
Return Values
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 Class
CImageAllocator::NonDelegatingAddRefIncrements the reference count for the owning filter.
HRESULT NonDelegatingAddRef( );
Return Values
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 Class
CImageAllocator::NonDelegatingReleaseDecrements the reference count for the owning filter.
HRESULT NonDelegatingRelease( );
Return Values
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 Class
CImageAllocator::NotifyMediaTypePasses the media type from a filter to the allocator.
void NotifyMediaType(
CMediaType *pMediaType
);Parameters
- pMediaType
- Media type the filter established.
Return Values
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 Class
CImageAllocator::SetPropertiesDetermines the size, number, and alignment of blocks.
HRESULT SetProperties(
ALLOCATOR_PROPERTIES * pRequest,
ALLOCATOR_PROPERTIES * pActual
);Parameters
- pRequest
- Requested allocator properties.
- pActual
- Allocator properties actually set.
Return Values
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.
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.