CDrawImage Class

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_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

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.

---

CDrawImage::CDrawImage

CDrawImage Class

Constructs a CDrawImage object.

CDrawImage(
  CBaseWindow *pBaseWindow
  );

Parameters

pBaseWindow

Window where drawing will occur.

Return Values

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

---

CDrawImage::DisplaySampleTimes

CDrawImage Class

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

void DisplaySampleTimes(
  IMediaSample *pSample
  );

Parameters

pSample

Sample containing time stamps.

Return Values

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

---

CDrawImage::DrawImage

CDrawImage Class

Entry point for drawing an image.

BOOL DrawImage(
  IMediaSample *pMediaSample
  );

Parameters

pMediaSample

Sample to draw.

Return Values

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.

void FastRender(
  IMediaSample *pMediaSample
  );

Parameters

pMediaSample

Sample to draw.

Return Values

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.

LONG GetPaletteVersion( );

Return Values

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.

void GetSourceRect(
  RECT *pSourceRect
  );

Parameters

pSourceRect

Holds the source rectangle.

Return Values

No return value.

---

CDrawImage::GetTargetRect

CDrawImage Class

Retrieves the current destination rectangle the draw object is using.

void GetTargetRect(
  RECT *pTargetRect
  );

Parameters

pTargetRect

Holds the target rectangle.

Return Values

No return value.

---

CDrawImage::IncrementPaletteVersion

CDrawImage Class

Increments the current palette version.

void IncrementPaletteVersion( );

Return Values

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.

void NotifyAllocator(
  BOOL bUsingImageAllocator
  );

Parameters

bUsingImageAllocator

Flag to indicate whether to use a CImageAllocator object allocator or not.

Return Values

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

void NotifyEndDraw(void);

Return Values

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.

void NotifyMediaType(
  CMediaType *pMediaType
  );

Parameters

pMediaType

Media type.

Return Values

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

---

CDrawImage::NotifyStartDraw

CDrawImage Class

Indicates the beginning of image rendering.

void NotifyStartDraw(void);

Return Values

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.

void ResetPaletteVersion( );

Return Values

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

Returns a scaled version of a provided source rectangle.

virtual RECT ScaleSourceRect(
  const RECT *pSource
  );

Parameters

pSource

Unscaled source rectangle.

Return Values

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.

void SetDrawContext( );

Return Values

No return value.

Remarks

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.

---

CDrawImage::SetSourceRect

CDrawImage Class

Sets the source rectangle for the video.

void SetSourceRect(
  RECT *pSourceRect
  );

Parameters

pSourceRect

New source rectangle.

Return Values

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.

void SetStretchMode( );

Return Values

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.

void SetTargetRect(
  RECT *pTargetRect
  );

Parameters

pTargetRect

New target area.

Return Values

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.

void SlowRender(
  IMediaSample *pMediaSample
  );

Parameters

pMediaSample

Sample to draw.

Return Values

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.

void UpdateColourTable(
  HDC hdc,
  BITMAPINFOHEADER *pbmi
  );

Parameters

hdc

Device context containing the sample image.

pbmi

BITMAPINFO structure containing the new palette.

Return Values

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.

BOOL UsingImageAllocator( );

Return Values

Returns one of the following values.

Value	Meaning
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.

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

Top of Page