CDrawImage Class

The CDrawImage 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

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 Off-screen draw DC.
m_pBaseWindow Owning video window object.
m_PaletteVersion Current palette version token.
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_SourceRect Source image rectangle.
m_StartSample Start time for the current sample.
m_TargetRect Destination rectangle.

Member Functions

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 Retrieves a scaled version of a provided source rectangle.
SetDrawContext Sets the window and off-screen 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.

CDrawImage::CDrawImage

CDrawImage Class

Constructs a CDrawImage object.

Syntax

CDrawImage(
    CBaseWindow *pBaseWindow
);

Parameters

pBaseWindow
Pointer to the window where drawing will occur.

Return Value

No return value.

Remarks

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) through 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. After 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.

CDrawImage::DisplaySampleTimes

CDrawImage Class

Displays time stamp of a sample on top of the image.

Syntax

void DisplaySampleTimes(
    IMediaSample *pSample
);

Parameters

pSample
Pointer to the sample containing time stamps.

Return Value

No return value.

Remarks

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 off-screen device context, it draws the times approximately 80 percent of the way down the image (and centered horizontally).
This is a protected member function.

CDrawImage::DrawImage

CDrawImage Class

Draws an image.

Syntax

BOOL DrawImage(
    IMediaSample *pMediaSample
);

Parameters

pMediaSample
Pointer to the sample to draw.

Return Value

No return value.

Remarks

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.

CDrawImage::FastRender

CDrawImage Class

Draws the sample image using the Microsoft Win32 BitBlt and StretchBlt functions.

Syntax

void FastRender(
    IMediaSample *pMediaSample
);

Parameters

pMediaSample
Pointer to the sample to draw.

Return Value

No return value.

Remarks

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.

CDrawImage::GetPaletteVersion

CDrawImage Class

Retrieves the current palette version.

Syntax

LONG GetPaletteVersion(void);

Return Value

Returns the palette version.

Remarks

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.

CDrawImage::GetSourceRect

CDrawImage Class

Retrieves the current source rectangle the draw object is using.

Syntax

void GetSourceRect(
    RECT *pSourceRect
);

Parameters

pSourceRect
Pointer to the source rectangle.

Return Value

No return value.

CDrawImage::GetTargetRect

CDrawImage Class

Retrieves the current destination rectangle the draw object is using.

Syntax

void GetTargetRect(
    RECT *pTargetRect
);

Parameters

pTargetRect
Pointer to the target rectangle.

Return Value

No return value.

CDrawImage::IncrementPaletteVersion

CDrawImage Class

Increments the current palette version.

Syntax

void IncrementPaletteVersion(void);

Return Value

No return value.

Remarks

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.

CDrawImage::NotifyAllocator

CDrawImage Class

Notifies the draw object which allocator the output pin is actually going to use.

Syntax

void NotifyAllocator(
    BOOL bUsingImageAllocator
);

Parameters

bUsingImageAllocator
Flag that specifies whether to use a CImageAllocator object allocator. For more information, see Remarks.

Return Value

No return value.

Remarks

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 Microsoft® 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.

CDrawImage::NotifyEndDraw

CDrawImage Class

Indicates the conclusion of image rendering.

Syntax

void NotifyEndDraw(void);

Return Value

No return value.

Remarks

This member function is used for performance measurements and just calls the MSR_STOP macro.

CDrawImage::NotifyMediaType

CDrawImage Class

Provides the image format for the draw object.

Syntax

void NotifyMediaType(
    CMediaType *pMediaType
);

Parameters

pMediaType
Pointer to the media type.

Return Value

No return value.

Remarks

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 usually call this just after completing a connection.
The function 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.

CDrawImage::NotifyStartDraw

CDrawImage Class

Indicates the beginning of image rendering.

Syntax

void NotifyStartDraw(void);

Return Value

No return value.

Remarks

This member function is used for performance measurements and just calls the MSR_START macro.

CDrawImage::ResetPaletteVersion

CDrawImage Class

Resets the current palette version.

Syntax

void ResetPaletteVersion(void);

Return Value

No return value.

Remarks

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.

CDrawImage::ScaleSourceRect

CDrawImage Class

Retrieves a scaled version of a provided source rectangle.

Syntax

virtual RECT ScaleSourceRect(
    const RECT *pSource
);

Parameters

pSource
Pointer to an unscaled source rectangle.

Return Value

Returns the scaled source rectangle (returns unscaled pSource by default).

Remarks

The base class implementation does not scale the source rectangle. Derived classes can override this to implement scaling, if required.

CDrawImage::SetDrawContext

CDrawImage Class

Sets the device contexts used for drawing.

Syntax

void SetDrawContext(void);

Return Value

No return value.

Remarks

The draw object always needs a device context for the window to draw images in. It might also need an off-screen 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, after it has initialized a window.

CDrawImage::SetSourceRect

CDrawImage Class

Sets the source rectangle for the video.

Syntax

void SetSourceRect(
    RECT *pSourceRect
);

Parameters

pSourceRect
Pointer to the new source rectangle.

Return Value

No return value.

Remarks

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.

CDrawImage::SetStretchMode

CDrawImage Class

Decides whether the video is to be stretched.

Syntax

void SetStretchMode(void);

Return Value

No return value.

Remarks

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.

CDrawImage::SetTargetRect

CDrawImage Class

Sets the target rectangle for the video.

Syntax

void SetTargetRect(
    RECT *pTargetRect
);

Parameters

pTargetRect
Pointer to the new target area.

Return Value

No return value.

Remarks

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.

CDrawImage::SlowRender

CDrawImage Class

Draws the sample image using SetDIBitsToDevice and StretchDIBits.

Syntax

void SlowRender(
    IMediaSample *pMediaSample
);

Parameters

pMediaSample
Pointer to the sample to draw.

Return Value

No return value.

Remarks

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.

CDrawImage::UpdateColourTable

CDrawImage Class

Updates the palette associated with a sample.

Syntax

void UpdateColourTable(
    HDC hdc,
    BITMAPINFOHEADER *pbmi
);

Parameters

hdc
Device context containing the sample image.
pbmi
Pointer to the BITMAPINFO structure containing the new palette.

Return Value

No return value.

Remarks

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.

CDrawImage::UsingImageAllocator

CDrawImage Class

Retrieves the type of samples to be drawn.

Syntax

BOOL UsingImageAllocator(void);

Return Value

Returns one of the following values.

TRUE Allocated through CreateDIBSection.
FALSE Not allocated through CreateDIBSection.

Remarks

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.

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	Off-screen draw DC.
m_pBaseWindow	Owning video window object.
m_PaletteVersion	Current palette version token.
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_SourceRect	Source image rectangle.
m_StartSample	Start time for the current sample.
m_TargetRect	Destination rectangle.

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	Retrieves a scaled version of a provided source rectangle.
SetDrawContext	Sets the window and off-screen 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.

TRUE	Allocated through CreateDIBSection.
FALSE	Not allocated through CreateDIBSection.