Ab3d.DXEngine diagnostics

Ab3d.DXEngine provides great analysis and diagnostics support.

The diagnostics tools can be used for the following purposes:

 

A simple way to diagnose the DXEngine is to use Visual Studio debugger and inspect many of the properties on the DXViewportView and DXViewportView.DXScene objects. DXScene object also provides the following methods to get additional details about the 3D scene: DumpSceneNodes, DumpRenderingQueues, GetSceneNodesDumpString or GetRenderingQueuesDumpString.

Advanced diagnostics with a lot of data and options is provided with using the DXEngine Diagnostics window that is defined in the Ab3d.DirectX.Client.Diagnostics project (available with full source code).

You have two options to use the Diagnostics window. One option is to include the Ab3d.DirectX.Client.Diagnostics project into your application. The other option is to use DXEngineSnoop tool.

To include the Ab3d.DirectX.Client.Diagnostics project into your application, add reference to the Ab3d.DirectX.Client.Diagnostics project and then add code to create and show an instace of DiagnosticsWindow object. When creating the DiagnosticsWindow object, you need to pass your DXViewportView as parameter. This approach is also used in the main Ab3d.DXEngine samples project where user can click on "Diagnostics" button to open the Diagnostics window.

The other option to show Diagnostics window do not require any change of your application. With using the DXEngineSnoop application that is installed into the "Program files\Ab3d.DXEngine\Tools" folder you can attach to a running application that is using Ab3d.DXEngine and open the Diagnostics window on the running application. See DXEngineSnoop section for more info.

 

Using Diagnostics window from the Ab3d.DirectX.Client.Diagnostics project

The following screenshot shows Diagnostics window from the Ab3d.DirectX.Client.Diagnostics project:

Ab3d.DXEngine Diagnostics window
(Note: all screenshot are from Ab3d.DXEngine version 2.1.6162; the actual controls can change in the future versions)

The red annotations show 5 main areas of the Diagnostics window:

  1. Version of the Ab3d.DXEngine library.
  2. Menu with additional actions and options (see Diagnostics menu below).
  3. Name of the currently used adapter (graphics card); used DirectX feature level (11.1 in this case); in case when DirectX device is created with debug flag, then "(debug layer)" text is displayed after the feature level.
  4. Warning and error messages info icon and number of messages (shown only when any warnings or errors occur). In case DXEngine logs a warning or error (for example if no camera is defined or if MeshGeometry3D have invalid TriangleIndices), then in icon with number of messages is shown. When clicking on the icon, a new window is opened with all messages shown. If the 3D scene is not rendered as expected, then a warning or error may indicate a reason for that.
  5. Rendering statistics (see below).

Rendering statistics details

The following rendering data are provided:

Most of the values displayed there can be get from the DXScene.Statistics property. For more information see the source code of the GetRenderingStatisticsDetails method in the DiagnosticsWindow.xaml.cs file.

 

Diagnostics menu

The following screenshot shows opened diagnostics menu:

Ab3d.DXEngine Diagnostics menu

Diagnostics menu provides the following actions and options:

The following screenshot shows a performance analysis result:

Ab3d.DXEngine Performance Analysis

 

DXEngineSnoop

DXEngineSnoop uses technology from WPF Snoop project (https://snoopwpf.codeplex.com/) that allows attaching to already running .Net application. When the DXEngineSnoop is attached to the running application, it tries to automatically find the DXViewportView from the visible UI controls. If the DXViewportView is found, the DXEngine Diagnostics window is shown (defined in the Ab3d.DirectX.Client.Diagnostics project).

The following screenshot shows main DXEngineSnoop window with "Ab3d.DirectX.ShaderFactory" application selected in the main ComboBox control.

DXEngineSnoop

In this case the user can click on "SNOOP" button and a Diagnostics window will be shown in the Ab3d.DirectX.ShaderFactory application.

DXEngineSnoop can be starter with "/auto" startup parameter. This will automatically attach to the first .Net application with DXEngine. This may be very handy because you can get the Diagnostics window quickly.

 

Troubleshooting DXEngineSnoop

Using DXEngineSnoop is not always possible. When attaching to the target application and trying to show Diagnostics window, many things can go wrong. For example the DXEngine or SharpDX version may not be compatible, the UI controls organization is not recognized and DXViewportView cannot be found. Though DXEngineSnoop tries to work on many different target environmantes, sometimes the Diagnostics window is not shown.

In most cases the DXEngineSnoop successfully attaches to the target progress, but then the problems begin when the DXViewportView is not found or when the Diagnostics window cannot be opened. The indication that the DXEngineSnoop is attached to the target process is that the title of the main window of the target process should get additional "(with DXEngineSnoop)" text.

In case the DXEngineSnoop is attaching to an application with different version of DXEngine, it is possible that the Visual Studio will stop on exception that some method or property is not implemented. Most of such exception are handled inside DXEngineSnoop so you should be able to click continue in Visual Studio.

If the Diagnostics window is still not shown, it is possible get detailed information about the attaching process with enabling logging. This can be done with starting the DXEngineSnoop with "/log:fileName" (fileName must be specified with full path) startup parameter. This will log information to Visual Studio Output window and also to the specified file name. After getting the log file name, please send it to support@ab4d.com email.