CDrawImage Class

The CDrawImage class is a helper class that manages drawing for a video renderer filter. All drawing operations are performed using GDI. This class does not provide any support for rendering with DirectDraw. The CDrawImage class requires that the owning filter also use the CBaseWindow class, which manages the video window. The CDrawImage constructor takes a pointer to the CBaseWindow object.

The following diagram shows the preferred way to use this class in a custom video renderer filter.

To use this class, do the following:

• When the pins connect, call the CDrawImage::NotifyMediaType and CDrawImage::NotifyAllocator methods.
• Whenever the media type changes, call NotifyMediaType again.
• Before any rendering occurs, call CDrawImage::SetDrawContext.
• Call CDrawImage::SetSourceRect if the source rectangle changes, and CDrawImage::SetTargetRect if the target rectangle changes.
• Manage the palette for palettized images, as described in the section on palettes that follows.

Allocators

The filter shown in the previous diagram uses a custom allocator class, CImageAllocator. This allocator creates DIBs in shared memory, using the GDI CreateDIBSection function. The samples created by the allocator are CImageSample objects.

If the filter owns the allocator for the connection, then the media samples are guaranteed to be CImageSample objects. In that case, the CDrawImage object can optimize drawing by using BitBlt or StretchBlt. Otherwise, it must use the slower SetDIBitsToDevice or StretchDIBits functions. The faster option is implemented by the CDrawImage::FastRender method, the slower option by the CDrawImage::SlowRender method. (Despite the name, you probably won't see a large performance hit in SlowRender, especially on newer hardware.)

Palettes

If the FastRender method is used for drawing and the image is palettized, then the filter needs to manage the palette, as follows:

• The CImageSample class contains a palette version number, stored in the DIBDATA structure. The value is initialized when the allocator creates the sample.
• The CDrawImage class also contains a palette version number, which is initialized on creation.
• Whenever the media type changes to a new palettized format, call CDrawImage::IncrementPaletteVersion. This method increments the CDrawImage object's palette version number. If the filter uses the CImagePalette class to manage the palette information, you can simply call CImagePalette::PreparePalette whenever the media type changes. The PreparePalette method increments the palette version only when necessary.
• The FastRender method compares the CDrawImage palette version against the sample's palette version. If the sample's version number lags behind the CDrawImage version number, the FastRender method calls CDrawImage::UpdateColourTable. The UpdateColourTable method sets the color table in the device context, using the GDI SetDIBColorTable function. Also, the palette version on the sample is updated to the current version number.
• If the pin reconnects, the filter should call CDrawImage::ResetPaletteVersion to reset the palette version. On pin reconnection, the allocator re-allocates all samples.

Requirements

Header: Declared in Winutil.h; include Streams.h.

Library: Use Strmbase.lib (retail builds) or Strmbasd.lib (debug builds).