In This Topic ▼

RasterImage and GDI/GDI+

The LEADTOOLS RasterImage class provides a platform independent representation of an image. It serves as a working area for image manipulation and conversion. LEADTOOLS functions use this class for accessing the image in memory and for maintaining the characteristics of the image. This topic discusses how to use the LEADTOOLS RasterImage class with the Windows GDI and GDI+ (System.Drawing) platforms.

Painting to a Device

In the Windows GDI and GDI+ platforms, you obtain a handle to a device or a window to paint on it. This handle can be either a GDI HDC handle or a GDI+ System.Drawing.Graphics object.

To paint a RasterImage object to a GDI or GDI+ handle, use the various RasterImagePainter.Paint methods. This is the equivalent to the Windows API BitBlt, StretchBlt and System.Drawing.Graphics.DrawImage methods.

Use the RasterImagePainter.FrameRegion and RasterImagePainter.FillRegion to paint only the area used by the current region in a RasterImage to a device. This is the equivalent of the Windows API FrameRgn / FillRegion and System.Drawing.Graphics.FillRegion methods.

In both GDI and GDI+, a palette must be set in the device when painting palletized images. The RasterImagePainter.Paint methods take care of palette handling internally when painting a palletized RasterImage object. However, you can use the RasterImagePainter.GetPaintColors and RasterImagePainter.GetPaintHPalette to get the palette to be used if required.

Painting on the surface of the LEADTOOLS Image

The Windows GDI contains many functions to draw on an HDC such as the MoveTo / LineTo and FillRect API. Use the RasterImagePainter.CreateLeadDC to obtain a GDI HDC object that represents the surface of a RasterImage. You can then use the various GDI methods to draw on this image.

Similarly, the GDI+ system System.Drawing.Graphics contains various methods to draw on the surface. Use the RasterImagePainter.CreateGraphics method to obtain a GDI+ System.Drawing.Graphics object that represents the surface of a RasterImage. You can then use the various GDI+ methods to draw on this image.

Image Conversion

The LEADTOOLS RasterImage class supports more pixel and color formats than the GDI DIB, HBITMAP and the GDI+ System.Drawing.Bitmap objects do. LEADTOOLS SDKs allow you to convert a RasterImage object to or from a GDI or GDI+ image. Also, if the pixel format is compatible, the RasterImage can be changed to or from a GDI or GDI+ image. This allows memory to be shared between these objects and any changes on one object to be reflected on the other.

Conversion to and from GDI Images

Use the RasterImage.ToDib and RasterImage.ToDibArray methods to convert a RasterImage to a GDI DIB (Device Independent Bitmap). Use RasterImage.FromDib and RasterImage.FromDibArray to convert a DIB to a RasterImage.

Use RasterImage.ChangeToDib to change a RasterImage to a GDI DIB and RasterImage.ChangeFromDib to change a DIB to a RasterImage while keeping both objects sharing the same memory (if the pixel and color format is compatible).

Use the RasterImageConverter.ToHBitmap method to convert a RasterImage to a GDI DDB (Device Dependent Bitmap). Use RasterImageConverter.FromHBitmap to convert a DDB to a RasterImage. Similarly, RasterImageConverter.ChangeFromHBitmap and RasterImageConverter.ChangeToHBitmap can be used to change a RasterImage to/from a DDB (if the pixel and color format is compatible).

Conversion to and from GDI+ Images

Use the RasterImageConverter.ConvertToImage method to convert a RasterImage to a GDI+ System.Drawing.Image object. Use RasterImageConverter.ConvertFromImage to convert a System.Drawing.Image object to a RasterImage.

GDI+ supports some of the pixel and color formats included in LEADTOOLS SDKs. If the RasterImage is compatible with GDI+, you can use the RasterImageConverter.ChangeToImage method to change a RasterImage to a GDI+ System.Drawing.Image object. After calling this method, both objects will share the same memory and changes to one will affect the other. To check if the RasterImage is compatible with GDI+, call the RasterImageConverter.TestCompatible method. The RasterImageConverter.MakeCompatible method can be used to force a RasterImage to be compatible with GDI+ by changing the internal color or pixel format if necessary.

Region Conversion

The LEADTOOLS RasterImage has an optional region area that can be used to restrict manipulation of the image data to a certain area. Use the RasterImage.GetRegion method to obtain the current region in a RasterImage as a RasterRegion object. Also, the RasterImage.SetRegion method can be used to set or combine a new region in a RasterImage.

Use the RasterRegionConverter.ConvertToRegion to convert a RasterRegion object to a GDI+ System.Drawing.Region object. The RasterRegionConverter.ConvertFromRegion method can be used to convert a GDI+ System.Drawing.Region to a RasterRegion.

Use the RasterRegionConverter.ConvertToRegionHandle to convert a RasterRegion object to a GDI HRGN object. The RasterRegionConverter.ConvertFromRegionHandle method can be used to convert a GDI HRGN to a RasterRegion.

Other Platforms

The default engine for Windows is an internal rendering engine which uses Windows GDI/GDI+. This engine is not available on other platforms (Linux, Android, macOS, iOS, and Universal Windows Platform (UWP)). LEADTOOLS offers a different draw engine (DrawEngineType.Multiplatform) that produces the same rendering results regardless of the platform being used. It can be used on all platforms. For more information, refer to LEADTOOLS Drawing Engine and Multi-Platform Considerations.