nuget
A winforms control that draws its whole content through the gpu accelerated directx 2d pipeline.
DxCanvas
00 Remarks
The control owns a dxgi flip model swap chain that is bound to its own window handle, so the winform paint cycle drives the gpu presentation directly:
- DxCanvas.OnPaint() opens a drawing frame on the swap chain
- the DxCanvas.Render event is raised, the handler draws through the
IGraphicsof the event data - DxCanvas.OnPaint() finishes the frame and presents it onto the window
The control never paints through gdi+ - the gpu canvas owns every pixel of the client area - so the background painting is suppressed and the opaque style is set, which removes the flickering frame of a gdi+ filled control.
The canvas is recreated together with the window handle, so docking, re-parenting and a dpi change are handled transparently. A removed gpu device is handled by the backend itself: the swap chain is rebuilt at the beginning of the next frame.
01 Syntax
Microsoft.VisualBasic.Drawing.DirectX.DxCanvas
02 Methods
| Name | Overloads | Summary |
|---|---|---|
| SaveImage | 1 | save the current canvas content into an image file |
| CaptureFrame | 1 | export the current canvas content as a raster image |
| OnHandleCreated | 1 | the canvas is not created here: dxgi rejects a swap chain that is created on a window which is still being created, so the canvas is created lazily by the first paint request ins… |
| OnHandleDestroyed | 1 | the window handle is destroyed, so the swap chain that is bound to it has to be released here, this also covers the disposal of the control. |
| OnPaintBackground | 1 | the directx canvas owns the whole client area, so the gdi+ background painting is suppressed here |
| CreateCanvas | 1 | create the directx canvas on the window of this control |
03 Properties
| Name | Overloads | Summary |
|---|---|---|
| Graphics | 1 | the gpu accelerated drawing canvas of this control |
| DeviceDescription | 1 | a short description of the gpu device that is in use |
| IsDeviceLost | 1 | was the gpu device removed? the swap chain is rebuilt on the next frame. |
| LastError | 1 | the message of the last rendering failure, Nothing means that every frame was drawn without an error |
| AutoClear | 1 | clear the canvas with the DxCanvas.BackgroundColor at the beginning of every frame |
| BackgroundColor | 1 | the color of the canvas background |
| VSync | 1 | should the frame submission wait for the vertical blank? |
04 Fields
| Name | Overloads | Summary |
|---|---|---|
| m_rendering | 1 | guard against the reentrant paint request of a nested message loop |
| m_capturePending | 1 | the pending capture request of DxCanvas.SaveImage()) and DxCanvas.CaptureFrame() |
05 Events
| Name | Overloads | Summary |
|---|---|---|
| Render | 1 | raised when the control needs to redraw its content |
06 Members
SaveImage(
String, ImageFormats)save the current canvas content into an image file
Remarks
The back buffer of the window swap chain only holds valid pixels while the frame is being submitted, so this forces a synchronous repaint of the control and captures the pixels of that frame: the DxCanvas.Render event is raised one more time to do so.
CaptureFrame
export the current canvas content as a raster image
Remarks
this works exactly like DxCanvas.SaveImage() but returns the image object instead of writing it into a file.
OnHandleCreated(
EventArgs)the canvas is not created here: dxgi rejects a swap chain that is created on a window which is still being created, so the canvas is created lazily by the first paint request instead.
OnHandleDestroyed(
EventArgs)the window handle is destroyed, so the swap chain that is bound to it has to be released here, this also covers the disposal of the control.
OnPaintBackground(
PaintEventArgs)the directx canvas owns the whole client area, so the gdi+ background painting is suppressed here
CreateCanvas
create the directx canvas on the window of this control
Graphics
the gpu accelerated drawing canvas of this control
Remarks
the canvas is only available after the window handle of the control has been created. The content that is drawn outside of the DxCanvas.Render event is presented by the next paint request.
DeviceDescription
a short description of the gpu device that is in use
IsDeviceLost
was the gpu device removed? the swap chain is rebuilt on the next frame.
LastError
the message of the last rendering failure, Nothing means that every frame was drawn without an error
AutoClear
clear the canvas with the DxCanvas.BackgroundColor at the beginning of every frame
Remarks
the back buffer of a flip model swap chain holds undefined pixels after the frame has been presented, so this should only be turned off when the render handler covers the whole canvas itself.
BackgroundColor
the color of the canvas background
VSync
should the frame submission wait for the vertical blank?
Remarks
waiting for the vertical blank keeps the presentation smooth, but it blocks the ui thread for up to one screen refresh interval per frame.
m_rendering
guard against the reentrant paint request of a nested message loop
m_capturePending
the pending capture request of DxCanvas.SaveImage() and DxCanvas.CaptureFrame()
Render
raised when the control needs to redraw its content
Remarks
the frame is already opened when the event is raised: everything that is drawn in the handler becomes visible when the frame is presented right after the event returns.