This class is a worker class for the owning CBaseWindow object. It handles the actual drawing operation from that class. To use this class, be sure to call CDrawImage::NotifyAllocator when the allocator has been agreed upon, and call CDrawImage::NotifyMediaType with a pointer to a CMediaType object (which must not be stack-based, because a pointer is maintained by this class rather than making a copy) when that is agreed.
When the palette changes, call CDrawImage::IncrementPaletteVersion, and before rendering call CDrawImage::SetDrawContext so that the class can obtain the handle to a device context (HDC) handles from the owning CBaseWindow object.
Protected Data Members
| Name | Description |
| m_bStretch | Flag to stretch the images. |
| m_bUsingImageAllocator | Flag to determine if samples share DIBSECTION structures. |
| m_EndSample | End time for the current sample. |
| m_hdc | Main window device context (DC). |
| m_MemoryDC | Offscreen draw DC. |
| m_pBaseWindow | Owning video window object. |
| m_perfidRenderNow | Moment when returned from draw (for performance logging). |
| m_perfidRenderTime | Time taken to render an image (for performance logging). |
| m_pMediaType | Pointer to the current media type format. |
| m_PaletteVersion | Current palette version token. |
| m_SourceRect | Source image rectangle. |
| m_StartSample | Start time for the current sample. |
| m_TargetRect | Destination rectangle. |
Member Functions
| Name | Description |
| CDrawImage | Constructs a CDrawImage object. |
| DisplaySampleTimes | Displays a time stamp of a sample on top of its image. |
| DrawImage | Looks after drawing an image to a window. |
| FastRender | Draws an image using BitBlt and StretchBlt. |
| GetPaletteVersion | Retrieves the currently installed palette version. |
| GetSourceRect | Retrieves the current source rectangle. |
| GetTargetRect | Retrieves the current target rectangle. |
| IncrementPaletteVersion | Increments the current palette version. |
| NotifyAllocator | Notifies the draw object which allocator is being used. |
| NotifyEndDraw | Indicates the conclusion of image rendering. |
| NotifyMediaType | Passes the media type established during connection. |
| NotifyStartDraw | Indicates the beginning of image rendering. |
| ResetPaletteVersion | Resets the current palette version. |
| ScaleSourceRect | Returns a scaled version of a provided source rectangle. |
| SetDrawContext | Sets the window and offscreen device contexts to draw with. |
| SetSourceRect | Sets the source rectangle for the video. |
| SetStretchMode | Determines whether it is necessary to stretch. |
| SetTargetRect | Sets the target rectangle for the window. |
| SlowRender | Uses the Microsoft® Win32® SetDIBitsToDevice and StretchDIBits functions to draw an image. |
| UpdateColourTable | Updates the palette held in a DIBSECTION structure. |
| UsingImageAllocator | Retrieves the type of samples to be drawn. |
Constructs a CDrawImage object.
CDrawImage(
CBaseWindow *pBaseWindow
);
No return value.
This class handles drawing of images through GDI. It works closely in conjunction with the CImageAllocator and CBaseWindow classes. It must know about the CImageAllocator class, because the draw code provides a faster drawing implementation if the buffers it is handed are created through the Microsoft® Win32® CreateDIBSection function. The image allocator creates this type of sample. It is told whether the buffers are allocated by a CImageAllocator object (or derived class) via the CDrawImage::NotifyAllocator member function.
If the buffers used to draw are not allocated by a compatible allocator, it will draw using the Win32 SetDIBitsToDevice family of APIs. The CBaseWindow class retrieves the window handle where the images are to be drawn. The device contexts that the drawing code should use are passed in through the CDrawImage::SetDrawContext member function.
The CImageAllocator, CImageSample, and CDrawImage classes are all tightly associated. The buffers that the image allocator creates are made using the 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 function.
These samples can then be passed to the draw object. The draw object knows the private format of the samples, and how to get the DIBDATA structure back from them. Once the draw object has obtained that information, it can pass a bitmap handle, 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.
Displays time stamp of a sample on top of the image.
void DisplaySampleTimes(
IMediaSample *pSample
);
No return value.
In debugging builds, it is often instructive to see the time stamps for images that the object is drawing. This member function gets the data pointer for the image the sample holds, along with its time stamps; then, using an offscreen device context, it draws the times approximately 80 percent of the way down the image (and centered horizontally).
This is a protected member function.
Entry point for drawing an image.
BOOL DrawImage(
IMediaSample *pMediaSample
);
No return value.
If the samples have been allocated by a CImageAllocator object (or a derived class), the images that the samples contain will be drawn using the Microsoft Win32 BitBlt or StretchBlt function. If not, they will be drawn using SetDIBitsToDevice or StretchDIBits. The client must call CDrawImage::NotifyAllocator prior to calling this member function to inform the CDrawImage object how the image buffers have been allocated. The object is informed each time the source or destination changes (through its CDrawImage::SetSourceRect and CDrawImage::SetTargetRect member functions). It uses this information to determine if it needs to stretch the image during the draw.
Draws the sample image using the Microsoft Win32 BitBlt and StretchBlt functions.
void FastRender(
IMediaSample *pMediaSample
);
No return value.
This protected member function is called by CDrawImage with a sample that contains an image buffer. The image buffer must have been allocated through the Win32 CreateDIBSection function and by a CImageAllocator object (or derived class). There are some performance benefits from drawing images created through this mechanism.
Retrieves the current palette version.
LONG GetPaletteVersion( );
Returns the palette version.
This member function is applicable only when using samples allocated through a CImageAllocator (or derived class) object. For more information about working with palettes, see the CDrawImage::UpdateColourTable member function.
Retrieves the current source rectangle the draw object is using.
void GetSourceRect(
RECT *pSourceRect
);
No return value.
Retrieves the current destination rectangle the draw object is using.
void GetTargetRect(
RECT *pTargetRect
);
No return value.
Increments the current palette version.
void IncrementPaletteVersion( );
No return value.
This member function is applicable only when using samples allocated through a CImageAllocator (or derived class) object. For more information about working with palettes, see the CDrawImage::UpdateColourTable member function.
Notifies the draw object which allocator the output pin is actually going to use.
void NotifyAllocator(
BOOL bUsingImageAllocator
);
No return value.
This member function tells the draw object whose allocator to use. This should be called with TRUE if the filter agrees to use an allocator based around the DirectShow™ CImageAllocator base class. These image buffers are made through CreateDIBSection. Otherwise this should be called with FALSE, and the images will be drawn using SetDIBitsToDevice and StretchDIBits.
Indicates the conclusion of image rendering.
void NotifyEndDraw(void);
No return value.
This member function is used for performance measurements and just calls the MSR_STOP macro.
Provides the image format for the draw object.
void NotifyMediaType(
CMediaType *pMediaType
);
No return value.
The draw object must know the format of the images it will be drawing. For the most part, this is so it can retrieve the palette when the images are 8-bit palettized. A filter using the draw class will normally call this just after completing a connection.
The method does not take a copy of the media type but just stores a pointer (for performance reasons). Therefore, the caller should ensure that the media type is not destroyed inadvertently.
Indicates the beginning of image rendering.
void NotifyStartDraw(void);
No return value.
This member function is used for performance measurements and just calls the MSR_START macro.
Resets the current palette version.
void ResetPaletteVersion( );
No return value.
This member function is applicable only when using samples allocated through a CImageAllocator (or derived class) object. For more information about working with palettes, see the CDrawImage::UpdateColourTable member function.
Returns a scaled version of a provided source rectangle.
virtual RECT ScaleSourceRect(
const RECT *pSource
);
Returns the scaled source rectangle (returns unscaled pSource by default).
The base class implementation does not scale the source rectangle. Derived classes can override this to implement scaling, if required.
Sets the device contexts used for drawing.
void SetDrawContext( );
No return value.
The draw object always needs a device context for the window to draw images in. It might also need an offscreen device context to select bitmaps into when using DIBSECTION buffers (for more details on these and CreateDIBSection, see the Microsoft Platform SDK documentation). This member function will typically be called by a filter using this class, once it has initialized a window.
Sets the source rectangle for the video.
void SetSourceRect(
RECT *pSourceRect
);
No return value.
The source rectangle should already have been validated before calling this member function so that the source rectangle specified will not extend over the edges of the available video.
Decides whether the video is to be stretched.
void SetStretchMode( );
No return value.
When the object is asked to draw an image, the object must know whether the video is being stretched, because it affects the function it calls (BitBlt or StretchBlt, for example). Rather than calculate this for every frame, it works it out just once when the source or destination rectangle is updated. This member function is called by SetSourceRect and SetTargetRect to manage this calculation.
This is a protected member function.
Sets the target rectangle for the video.
void SetTargetRect(
RECT *pTargetRect
);
No return value.
The destination rectangle should already have been validated before calling this member function, so that the destination specified will not define an empty playback area.
Draws the sample image using SetDIBitsToDevice and StretchDIBits.
void SlowRender(
IMediaSample *pMediaSample
);
No return value.
The sample provided should contain the image to draw and should match the format as specified to the draw object through NotifyMediaType.
This is a protected member function.
Updates the palette associated with a sample.
void UpdateColourTable(
HDC hdc,
BITMAPINFOHEADER *pbmi
);
No return value.
This member function is applicable only when using samples allocated through a CImageAllocator (or derived class) object. CImageAllocator creates samples that are created with the Microsoft Win32 CreateDIBSection function. When a palettized buffer is allocated through CreateDIBSection, a palette is passed in that is associated with that buffer.
Should the palette be changed, the new palette must be associated with the buffer before drawing it (this is done through the Win32 SetDIBColorTable function and internally with the UpdateColourTable member function). The drawing code knows to update the palette because the palette version it stores in the sample will differ from the palette version it keeps internally.
In essence, the sample gets an initial palette version when created. When the palette is changed (probably by a filter), it tells the draw object to increment its palette version (through the IncrementPaletteVersion member function). When the draw object next comes to draw the sample, it will see that the sample has an old palette version and will know to call UpdateColourTable on it.
The draw object knows the type of buffer used for samples through the NotifyAllocator member function. If it is called with TRUE, the buffers passed to it must be allocated by a CImageAllocator (or derived class) object. If it is called with FALSE, the buffers should be allocated in standard system memory (or other memory accessible to GDI in the same manner).
When the allocator is decommitted, it will typically delete all the samples it holds on to. When it is subsequently committed, the samples will be created again with their initial palette versions. At this point, the allocator should also reset the palette version in the draw object so that they remain in sync. An allocator can do this by calling the ResetPaletteVersion member function.
This is a protected member function.
Retrieves the type of samples to be drawn.
BOOL UsingImageAllocator( );
Returns one of the following values.
| Value | Meaning |
| TRUE | Allocated through CreateDIBSection. |
| FALSE | Not allocated through CreateDIBSection. |
This member function is applicable only when using samples allocated through a CImageAllocator (or derived class) object. For more information about working with palettes and the image allocator, see the CDrawImage::UpdateColourTable member function.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.