windowsforms-119441-common-features-graphics-performance-and-high-dpi-directx-hardware-acceleration.md
DirectX hardware acceleration allows your application to utilize a client machine’s video card (integrated or dedicated) to render DevExpress controls. DirectX acceleration boosts applications’ performance on 4K displays, where large data applications rendered with standard GDI+ can be unresponsive.
You can enable DirectX rendering in the DevExpress Project Settings window.
To enable DirectX rendering, you can also call the static WindowsFormsSettings.ForceDirectXPaint method when the application starts.
using DevExpress.XtraEditors;
namespace WindowsFormsApplication1 {
static class Program {
/// <summary>
/// The application's main entry point.
/// </summary>
[STAThread]
static void Main() {
WindowsFormsSettings.ForceDirectXPaint();
Application.EnableVisualStyles();
Application.SetCompatibleTextRenderingDefault(false);
Application.Run(new Form1());
}
}
}
Public Class Form1
Shared Sub Main()
'Add your code here
DevExpress.XtraEditors.WindowsFormsSettings.ForceDirectXPaint()
Application.EnableVisualStyles()
Application.SetCompatibleTextRenderingDefault(False)
Application.Run(New Form1) 'Specify the startup form
End Sub
End Class
The ForceDirectXPaint method enables the DirectX hardware acceleration for the following controls:
To revert individual controls to the GDI+ engine, disable their UseDirectXPaint settings.
gridControl1.UseDirectXPaint = DevExpress.Utils.DefaultBoolean.False;
gridControl1.UseDirectXPaint = DevExpress.Utils.DefaultBoolean.False
The following DevExpress controls’ default UseDirectXPaint value is equal to DefaultBoolean.False. For these controls, calling the static WindowsFormsSettings.ForceDirectXPaint method alone has no effect. You should call the global static method and manually set their UseDirectXPaint properties to DefaultBoolean.True to enable the DirectX acceleration.
CalendarControlBase descendants (for example, CalendarControl)
TextEdit-based editors that support Advanced Mode (see the RepositoryItemTextEdit.UseAdvancedMode property).
pictureEdit1.UseDirectXPaint = DevExpress.Utils.DefaultBoolean.True;
pictureEdit1.UseDirectXPaint = DevExpress.Utils.DefaultBoolean.True
To use DirectX rendering in the PDF Viewer control, set the PdfViewer.RenderingEngine property to DirectX.
To use DirectX rendering for the DocumentViewer control, enable its UseDirectXPaint property. The WindowsFormsSettings.ForceDirectXPaint static method has no effect for this control.
You can change the parent class of a Form to DevExpress.XtraEditors.DirectXForm. All controls that reside inside such forms and support the DirectX rendering run in DirectX mode. Controls that do not support DirectX are hidden.
See this class description for more information: DirectXForm.
Displays
Applications benefit from DirectX acceleration on any display, but these advantages are more evident at higher resolutions (2K, WQHD, WQXGA, 4K, etc.).
Virtual Memory
Each control painted in DirectX mode requires its own DirectX device. You can set the optimal DirectX device number through the DevExpress.Utils.DirectXPaint.DirectXProvider.DeviceLimit property. If the current device number is equal to or higher than this DeviceLimit property value, new controls that need to be shown will still be painted with DirectX acceleration. However, the application tries to release devices for currently hidden controls to keep the number of active devices below the threshold, which reduces the total virtual memory consumption.
DirectX hardware acceleration imposes the following restrictions on the API:
|
Unsupported API
|
Recommended Action
| | --- | --- | |
All API accessed through the e.Graphics property (for example, when handling custom draw events).
|
Utilize the GraphicsCache class API (available through the e.Cache property).
| |
Methods that use the Graphics class objects as parameters (for instance, the ControlPaint class methods).
|
No replacement, use similar methods instead.
| |
The AppearanceObject.CalcDefaultTextSize(Graphics g) method overload
|
Replace with the AppearanceObject.CalcDefaultTextSize(GraphicsCache cache) overload
| |
The following AppearanceObject.CalcTextSizeInt method overloads:
|
Replace with the following overloads:
| |
The following AppearanceObject.CalcTextSize method overloads:
|
Replace with the following overloads:
| |
The AppearanceObject.FontHeight property is obsolete
|
No replacement for this property. Revisit your code and use a different approach.
| |
The Pen.Alignment property is ignored.
|
There are no DirectX-compatible counterparts for this property.
| |
Certain fonts will not resolve, including fonts that are not installed locally
|
Not all GDI fonts can be mapped to equivalent DirectX fonts. Only locally installed fonts can be mapped to.
| |
The Color.Transparent color
|
The DirectX engine does not support the transparent color. Change the element color or turn off the DirectX Acceleration for this control.
| |
The InterpolationMode property in Graphics, GraphicsCache, and RepositoryItemPictureEdit classes supports only HighQualityBicubic and NearestNeighbor values.
| | |
CompositingMode, CompositingQuality, TextRenderingHint, SmoothingMode, and PixelOffsetMode properties in Graphics and GraphicsCache classes are ignored.
| |
The DevExpress.Utils.Trimming.EllipsisPath mode is not supported.
|
To detect all the unsupported APIs, call the static WindowsFormsSettings.ForcePaintApiDiagnostics method and set the security level as the first parameter:
Throw - unsupported APIs result in exceptions;
Trace - unsupported APIs display result in warnings, displayed in Visual Studio’s “Output” window;
Disable - ignores unsupported API;
Default - acts as “Trace” if DirectX and\or Per-Monitor HiDPI support is enabled; otherwise, as “Disable”.
using DevExpress.Utils.Diagnostics;
//disable the API tracing
DevExpress.XtraEditors.WindowsFormsSettings.ForcePaintApiDiagnostics(PaintApiDiagnosticsLevel.Disable);
Imports DevExpress.Utils.Diagnostics
'disable the API tracing
DevExpress.XtraEditors.WindowsFormsSettings.ForcePaintApiDiagnostics(PaintApiDiagnosticsLevel.Disable)
The ForcePaintApiDiagnostics method’s second parameter allows you to specify a custom behavior:
//The following sample implements the custom logging:
DevExpress.XtraEditors.WindowsFormsSettings.ForcePaintApiDiagnostics(PaintApiDiagnosticsLevel.Throw,
(apiLevel, api) =>
{
System.Console.WriteLine(apiLevel.ToString() + ": " + api);
//Suppress the Throw mode exceptions
return PaintApiDiagnosticsLevel.Disable;
});
'the following sample implements the custom logging
DevExpress.XtraEditors.WindowsFormsSettings.ForcePaintApiDiagnostics(PaintApiDiagnosticsLevel.Throw, Function(apiLevel, api)
'suppress the Throw mode exceptions
System.Console.WriteLine(apiLevel.ToString() & ": " & api)
Return PaintApiDiagnosticsLevel.Disable
End Function)
Metafile images are rasterized in DirectX mode. As a result, such images can appear blurry if stretched or zoomed.
DevExpress DirectX rendering is available only for graphics cards that support Direct3D Feature Levels equal to or higher than 11. To check your GPU’s supported Feature Levels, run the “DirectX Diagnostic Tool”: press “Win+R” to launch the “Run” dialog and type in the dxdiag command. Alternatively, in Visual Studio go to “Help | About Microsoft Visual Studio” and click the “DxDiag” button.
You can enable the Test Mode if your machine has Feature Levels of 10_2 or lower. This mode forces the application to use the DirectX rendering regardless of supported Feature Levels. Note that this mode is intended for debugging only.
#if DEBUG
DevExpress.Utils.DirectXPaint.DirectXProvider.EnableTestMode()
#endif
#If DEBUG Then
DevExpress.Utils.DirectXPaint.DirectXProvider.EnableTestMode()
#End If
You can also set the DirectXRenderLogMode property to RaiseDeviceCreationFailedEvent and handle the DeviceCreationFailed event to trace all cases when the application is unable to create a DirectX device.
DevExpress.Utils.DirectXPaint.DirectXProvider.DirectXRenderLogMode = DevExpress.Utils.DirectXPaint.DirectXRenderLogMode.RaiseDeviceCreationFailedEvent;
DevExpress.Utils.DirectXPaint.DirectXProvider.DeviceCreationFailed += DirectXProvider_DeviceCreationFailed;
private void DirectXProvider_DeviceCreationFailed(object sender, DevExpress.Utils.DirectXPaint.DeviceCreationFailedEventArgs e)
{
//read the e.Log parameter
}
DevExpress.Utils.DirectXPaint.DirectXProvider.DirectXRenderLogMode = DevExpress.Utils.DirectXPaint.DirectXRenderLogMode.RaiseDeviceCreationFailedEvent
AddHandler DevExpress.Utils.DirectXPaint.DirectXProvider.DeviceCreationFailed, AddressOf DirectXProvider_DeviceCreationFailed
Private Sub DirectXProvider_DeviceCreationFailed(sender As Object, e As DevExpress.Utils.DirectXPaint.DeviceCreationFailedEventArgs)
'read the e.Log parameter
End Sub