## 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::Alloc

CImageAllocator Class

Creates 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::CheckSizes

CImageAllocator Class

Internal 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::CImageAllocator

CImageAllocator Class

Constructs 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::CreateDIB

CImageAllocator Class

Calls 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::CreateImageSample

CImageAllocator Class

Creates 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::Free

CImageAllocator Class

Deletes 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::NonDelegatingAddRef

CImageAllocator Class

Increments 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::NonDelegatingRelease

CImageAllocator Class

Decrements 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::NotifyMediaType

CImageAllocator Class

Passes 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::SetProperties

CImageAllocator Class

Determines 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.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.