August 6, 2020

Using Direct2D and GDI+

Direct2D is an API that provides Win32 developers with the ability to perform 2-D graphics rendering tasks with superior performance and visual quality.

Direct2D is a hardware-accelerated. That is it make use of the GPU whenever possible. This is what gives high performance and high-quality rendering for 2-D geometry, bitmaps, and text. But when a GPU is not available, Direct2D transparently fallback to software to replace the missing GPU functions.

The Direct2D API is designed to interoperate with existing code that uses GDI, GDI+, or Direct3D.

Applications that use Direct2D for graphics can deliver higher visual quality than what can be achieved using GDI. Direct2D uses per-primitive antialiasing to deliver smoother looking curves and lines in rendered content. There is also full support for transparency and alpha blending when rendering 2D primitives.

Windows GDI+ is the portion of the Windows operating system that provides two-dimensional vector graphics, imaging, and typography. GDI+ improves on Windows Graphics Device Interface (GDI) (the graphics device interface included with earlier versions of Windows) by adding new features and by optimizing existing features.

In this demo, we will use GDI+ for file I/O of image files and Direct2D for drawing the images on screen.

The demo is – as any good demo – a minimal application aimed at demonstrating how to read an image file (JPG, PNG, …) and show it on screen with zoom/pan/rotate and flip operation.


Demo code organization

For the purpose of this demo, the code is divided in two parts: a VCL component to expose Direct2D screen area and a form showing a user interface where an image file is shown and a few buttons to execute simple operations such as zoom, pan, rotate and flip.


TAcceleratedPaintPanel component

I created this component to have something similar to the standard TPaintBox but using a Direct2D canvas. I named this component TAcceleratedPaintPanel to avoid conflict with any existing component.

The component code is very simple since Delphi VCL already has a Direct2D canvas which hides most of the complexity. So, we simply start from a TPanel, activate his Direct2D canvas and expose an OnPaint method which can then be used on any form making use of TAcceleratedPaintPanel.


unit AcceleratedPaintPanel;


interface


uses

    Winapi.Messages, Winapi.D2D1,

    System.Classes,

    Vcl.Graphics, Vcl.ExtCtrls, Vcl.Direct2D;


type

    TCustomAcceleratedPaintPanel = class(TPanel)

    private

        FD2DCanvas             : TDirect2DCanvas;

        FPrevRenderTarget      : IntPtr;

        FOnPaint               : TNotifyEvent;

        FOnCreateRenderTarget  : TNotifyEvent;

        function  CreateD2DCanvas: Boolean;

        procedure WMEraseBkGnd(var Msg: TMessage); message WM_ERASEBKGND;

        procedure WMPaint(var Msg: TWMPaint); message WM_PAINT;

        procedure WMSize(var Msg: TWMSize); message WM_SIZE;

    protected

        procedure CreateWnd; override;

        function  GetRenderTarget : ID2D1HwndRenderTarget;

        procedure TriggerCreateRenderTarget; virtual;

    public

        destructor Destroy; override;

        procedure Paint; override;

        property D2DCanvas             : TDirect2DCanvas

                                                   read  FD2DCanvas;

        property RenderTarget          : ID2D1HwndRenderTarget

                                                   read  GetRenderTarget;

        property OnPaint               : TNotifyEvent

                                                   read  FOnPaint

                                                   write FOnPaint;

        property OnCreateRenderTarget  : TNotifyEvent

                                                   read  FOnCreateRenderTarget

                                                   write FOnCreateRenderTarget;

    end;


implementation


uses

    Windows, SysUtils, Controls;


destructor TCustomAcceleratedPaintPanel.Destroy;

begin

    FreeAndNil(FD2DCanvas);

    inherited Destroy;

end;


function TCustomAcceleratedPaintPanel.CreateD2DCanvas: Boolean;

begin

    try

        FD2DCanvas := TDirect2DCanvas.Create(Handle);

        Result     := TRUE;

    except

        Result     := FALSE;

    end;

    TriggerCreateRenderTarget;

end;


procedure TCustomAcceleratedPaintPanel.CreateWnd;

begin

    inherited;

    if (Win32MajorVersion < 6) or (Win32Platform <> VER_PLATFORM_WIN32_NT) then

        raise Exception.Create('Your Windows version do not support Direct2D');

    if not CreateD2DCanvas then

        raise Exception.Create('Unable to create Direct2D canvas');

end;


function TCustomAcceleratedPaintPanel.GetRenderTarget: ID2D1HwndRenderTarget;

begin

    if FD2DCanvas <> nil then begin

        Result := FD2DCanvas.RenderTarget as ID2D1HwndRenderTarget;

        if FPrevRenderTarget <> IntPtr(Result) then begin

            FPrevRenderTarget := IntPtr(Result);

            TriggerCreateRenderTarget;

        end;

    end

    else

        Result := nil;

end;


procedure TCustomAcceleratedPaintPanel.TriggerCreateRenderTarget;

begin

    if Assigned(FOnCreateRenderTarget) then

        FOnCreateRenderTarget(Self);

end;


procedure TCustomAcceleratedPaintPanel.Paint;

begin

    D2DCanvas.Font.Assign(Font);

    D2DCanvas.Brush.Color := Color;

    if csDesigning in ComponentState then begin

        D2DCanvas.Pen.Style   := psDash;

        D2DCanvas.Brush.Style := bsSolid;

        D2DCanvas.Rectangle(0, 0, Width, Height);

    end;

    if Assigned(FOnPaint) then

        FOnPaint(Self);

end;


procedure TCustomAcceleratedPaintPanel.WMEraseBkGnd(var Msg: TMessage);

begin

    Msg.Result := 1;

end;


procedure TCustomAcceleratedPaintPanel.WMPaint(var Msg: TWMPaint);

var

    PaintStruct: TPaintStruct;

begin

    BeginPaint(Handle, PaintStruct);

    try

        FD2DCanvas.BeginDraw;

        try

            Paint;

        finally

            FD2DCanvas.EndDraw;

        end;

    finally

        EndPaint(Handle, PaintStruct);

    end;

end;


procedure TCustomAcceleratedPaintPanel.WMSize(var Msg: TWMSize);

var

    Size: D2D1_SIZE_U;

begin

    if FD2DCanvas <> nil then begin

        Size := D2D1SizeU(Width, Height);

        ID2D1HwndRenderTarget(FD2DCanvas.RenderTarget).Resize(Size);

    end;

    inherited;

end;


end


TAcceleratedPaintPanel is the actual component. As always with Delphi, it is the “custom” version with properties and event published. This is the one registered in the component package.

In the source code for this article, you’ll find two packages: one run time and one design time. Before opening the demo project, you must compile both packages and install the design time package. If you open the demo project before installing the design time package, Delphi will complain about mission TAcceleratedPaintPanel component, asking if you want to cancel or ignore. Be sure to select “cancel” because if you select “ignore”, Delphi will remove the missing component from the form and obviously this will break the code!


Loading an image file with GDI+

It is obvious that to display an image file (A picture stored in a JPG or PNG file), the file must be read in memory and then transferred to video memory.

A JPG or PNG file is not a simple array of pixel: they are compressed with or without loss. GDI+ offer functions to read and decompress image files of various well-known formats.

In Delphi winapi implementation there is a class named TGPBitmap which handle reading and writing image file in all supported formats. Opening an image file is as simple as creating an instance of TGPBitmap, passing the file name as argument. When done, to close the file, just destroy the class instance.

This looks like this:

    GPBitmap := TGPBitmap.Create(FileName);

    try

        // Code making use of the image data, removed for

        // simplicity here.

    finally

       FreeAndNil(GPBitmap);

    end;


Preparing a Direct2D bitmap

Once the image file is opened by GDI+, we can ask to access to the uncompressed image data. On the fly, the GDI+ can change the pixel format to suit any need. Direct2D needs pixel in ARGB format, that is 4 bytes per pixel: the usual 3 bytes for red, green and blue components and a 4th byte for the so-called alpha-channel used for transparency.

A simple call to TGPBitmap.LockBits will do:

var

    BitmapBuf        : array of Byte;  

    BmpData          : TBitmapData;

begin

    SetLength(BitmapBuf, GPBitmap.GetHeight * GPBitmap.GetWidth * 4);

    if GPBitmap.LockBits(MakeRect(0, 0,

                                  Integer(GPBitmap.GetWidth),

                                  Integer(GPBitmap.GetHeight)),

                         ImageLockModeRead,

                         PixelFormat32bppARGB,

                         BmpData) <> TStatus.Ok then

        raise Exception.Create('GPBitmap.LockBits failed');

end;


Obviously we need a buffer to hold the pixel data. We use an array of byte for the purpose and we need 4 bytes per pixel (4 x width x height).

When calling LockBits, we have to pass 4 arguments. The first is the region of interest rectangle, which is the full bitmap here. The second is how we intend to use the data in memory, here just read the pixels. The third is the pixel format that we need, not necessarily the same as the pixel format inside the file. LockBits is smart enough to do the conversion for us. And finally, the fourth argument is the buffer where data will be loaded.

Now having the data in memory, we can tell Direct2D to take it into his own bitmap format:

var

    BitmapProp : TD2D1BitmapProperties;

begin

    BitmapProp.DpiX                  := 0;

    BitmapProp.DpiY                  := 0;

    BitmapProp.PixelFormat.Format    := DXGI_FORMAT_B8G8R8A8_UNORM;

    BitmapProp.PixelFormat.AlphaMode := D2D1_ALPHA_MODE_PREMULTIPLIED;


    RenderTarget.CreateBitmap(D2D1SizeU(GPBitmap.GetWidth,

                                        GPBitmap.GetHeight),

                              BmpData.Scan0,

                              BmpData.Stride,

                              BitmapProp,

                              Result);

end;


RenderTarget is an interface from Direct2D API. It is accessible thru Delphi VCL D2DCanvas.


Encapsulating LoadBitmap in a function

What we saw in the previous sections can be encapsulated in a single function taking the filename and producing the Direct2D bitmap we will use each time the UI needs to be redrawn.

It the code below, you’ll notice reference to “transform”. This will be explained later in this document.

function TDirect2DDemoMainForm.LoadBitmap(const FileName : String): Boolean;

var

    GPBitmap     : TGPBitmap;

begin

    try

        GPBitmap := TGPBitmap.Create(FileName);

        try

            if (GPBitmap.GetWidth = 0) or (GPBitmap.GetHeight = 0) then begin

                ShowMessage('Invalid file');

                Result := FALSE;

                Exit;

            end;


            FBitmapToPaint := CreateDirect2DBitmap(

                            AcceleratedPaintPanel1.D2DCanvas.RenderTarget,

                            GPBitmap);

            // Reset transforms to something the user expects

            FFlipHoriz    := FALSE;

            FFlipVert     := FALSE;

            FRotateFactor := 0.0;

            ZoomFull;

            PanCenter;

            ComputeTransform;


            // Calling Invalidate will force the component to redraw which

            // in turn will trigger OnPaint event and our paint handler which

            // draw the image on screen

            AcceleratedPaintPanel1.Invalidate;

            Result := TRUE;

        finally

            FreeAndNil(GPBitmap);

        end;

    except

        on E:Exception do begin

            ShowMessage(E.ClassName + ': ' + E.Message);

            Result := FALSE;

        end;

    end;

end;


Drawing the image

TAcceleratedPaintPanel has an OnPaint event which is triggered each time Windows request the repaint the window. The OnPaint event handler has to draw the image. This is done by calling a single method:

    AcceleratedPaintPanel1.RenderTarget.DrawBitmap(FBitmapToPaint);

RenderTarget is a Direct2D interface exposed by TAcceleratedPaintPanel. This interface has a lot of methods among which DrawBitmap that can draw a Direct2D bitmap on screen. When called with a single argument, the full bitmap is drawn as is on the window top left corner.


Direct2D transforms

Drawing a bitmap on the top left corner is not what we need in most application. We probably want to resize the bitmap so that it fits the window, maybe we want to move it left or right (panning), rotate it, flip it, zoom it. This is where Direct2D transforms comes in play.

A transform specifies how to map the points of an object from one coordinate space to another or from one position to another within the same coordinate space. This mapping is described by a transformation matrix, defined as a collection of three rows with three columns of floating-point values.

This may sound complex. Actually, it is not. We don’t really care about that matrix. It is enough to know how to initialize it to pan, zoom, rotate and flip the bitmap. To combine several transforms, we just have to multiply each individual transform involved. For example, to center a bitmap into the window, we use a scaling matrix (Zoom) and a translation matrix (panning).

Technically, a transform matrix is a record having nine single precision floating point and an operator overloading to multiply two matrices. The result is a matrix representing the two transforms.

There also some record helpers to easily create common transform matrices. For example, to create a transform matrix to zoom by a factor of 2, you write:

    Zoom := TD2DMatrix3x2F.Scale(D2D1SizeF(2.0, 2.0), D2D1PointF(0, 0));

The first argument is the zoom factor along width and height. The second argument is the zoom center.

There are similar helpers for the other transforms. Missing is the flip transform. Flipping around a horizontal or vertical axis is like looking a printed picture by transparency from the reverse side. The matrices are:

    const FlipH : D2D_MATRIX_3X2_F = (

      _11:-1.0; _12: 0.0;

      _21: 0.0; _22: 1.0;

      _31: 0.0; _32: 0.0;);

    const FlipV : D2D_MATRIX_3X2_F = (

      _11: 1.0; _12: 0.0;

      _21: 0.0; _22:-1.0;

      _31: 0.0; _32: 0.0;);


An important note: transform can be combined using the multiply operator but the order is important! Scaling * translating is not the same as translating * scaling.

In the demo application, I use a number of fields to specify the transform to be applied to the bitmap when displayed:

        FRotateFactor : Double;

        FZoomFactor   : Double;

        FPanLeft      : Integer;

        FPanTop       : Integer;

        FFlipHoriz    : Boolean;

        FFlipVert     : Boolean;


And one more field is used to store the result of all combined transforms:

       FTransform   : TD2DMatrix3X2F;

Each time one of the fields value is changed, a new combined transform is computed and then the paint panel is invalidated, forcing a redraw.

procedure TDirect2DDemoMainForm.ComputeTransform;

var

    Scaling      : TD2DMatrix3X2F;

    Translation  : TD2DMatrix3X2F;

    Rotation     : TD2DMatrix3X2F;

    FlippingH    : TD2DMatrix3X2F;

    FlippingHT   : TD2DMatrix3X2F;

    FlippingV    : TD2DMatrix3X2F;

    FlippingVT   : TD2DMatrix3X2F;

    Size         : TD2D1SizeU;

begin

    if not Assigned(FBitmapToPaint) then begin

        FTransform := TD2DMatrix3x2F.Identity;

        Exit;

    end;


    FBitmapToPaint.GetPixelSize(Size);


    if Abs(FZoomFactor - 1.0) <= 1E-5 then

        Scaling := TD2DMatrix3x2F.Identity

    else

        Scaling := TD2DMatrix3x2F.Scale(D2D1SizeF(FZoomFactor, FZoomFactor),

                                        D2D1PointF(0, 0));

    if Abs(FRotateFactor) <= 1E-5 then

        Rotation := TD2DMatrix3x2F.Identity

    else

        Rotation := TD2DMatrix3x2F.Rotation(FRotateFactor,

                                            Size.Width div 2,

                                            Size.Height div 2);


    Translation := TD2DMatrix3x2F.Translation(FPanLeft, FPanTop);


    if not FFlipHoriz then begin

        FlippingH     := TD2DMatrix3x2F.Identity;

        FlippingHT    := TD2DMatrix3x2F.Identity;

    end

    else begin

        FlippingH._11 := -1.0;   FlippingH._12 := 0.0;

        FlippingH._21 :=  0.0;   FlippingH._22 := 1.0;

        FlippingH._31 :=  0.0;   FlippingH._32 := 0.0;

        FlippingHT    := TD2DMatrix3x2F.Translation(-Size.width, 0);

    end;


    if not FFlipVert then begin

        FlippingV     := TD2DMatrix3x2F.Identity;

        FlippingVT    := TD2DMatrix3x2F.Identity;

    end

    else begin

        FlippingV._11 :=  1.0;   FlippingV._12 :=  0.0;

        FlippingV._21 :=  0.0;   FlippingV._22 := -1.0;

        FlippingV._31 :=  0.0;   FlippingV._32 :=  0.0;

        FlippingVT    := TD2DMatrix3x2F.Translation(0, -Size.Height);

    end;


    FTransform := FlippingVT * FlippingV *

                  FlippingHT * FlippingH *

                  Rotation   * Scaling   * Translation;

end;


Flipping are combined with a translation so that the flip axis remains in the middle of the bitmap.

Now that we have transforms, we can see the complete OnPaint event handler:

procedure TDirect2DDemoMainForm.AcceleratedPaintBox1Paint(Sender : TObject);

begin

    // Paint background

    AcceleratedPaintPanel1.RenderTarget.Clear(D2D1ColorF(clSilver));

    // Paint bitmap, if any

    if FBitmapToPaint <> nil then begin

        AcceleratedPaintPanel1.RenderTarget.SetTransform(FTransform);

        AcceleratedPaintPanel1.RenderTarget.DrawBitmap(FBitmapToPaint);

    end;

end;

 


Source code

Full source code is available on Github. It is subject to Mozilla Public License V2.0.

https://github.com/fpiette/Direct2DDemo

Fran├žois Piette

Embarcadero MVP


No comments: