DXEngine Quick start

This quick start page describes how easily is to convert existing WPF 3D application to an application that uses Ab3d.DXEngine and renders the 3D scene with DirectX 11. To do the conversion, do the following:

1. Ab3d.DXEngine can be used for .Net 4.0 Client profile and newer framework versions.

2. 1. If your application is targeting .Net 4.0 Client profile (or .Net 4.0), then you need to use libraries from the bin\net40 folder (version revision number 40 or 1040). You also need to use SharpDX version 2.6.3. This is the latest version of SharpDX library that works with .Net 4.0.

      In this case you need to add the following references to the project (all the libraries can be found in the bin\net40 folder; you can also use SharpDX libraries from nuget package):

      • Ab3d.DXEngine (core classes that can render the 3D scene; assembly revision number 40 or 1040)
      • Ab3d.DXEngine.Wpf (classes that convert existing WPF 3D objects into DXEngine 3D scene; assembly revision number 40 or 1040)
      • SharpDX (core library for the managed DirectX wrapper)
      • SharpDX.Direct3D11 (managed DirectX 11 classes)
      • SharpDX.DXGI (managed DirectX DXGI classes)

   2. If your application is targeting .Net 4.5 or newer framework, then you can use the assemblies listed in the previous point or you can use the libraries from the bin\net45 folder. In this case you can use the latest version of SharpDX libraries.

      In SharpDX version 3.0 some base math types like Vector3, Matrix, Color3, etc. were moved from core SharpDX assemblies to the SharpDX.Mathematics assembly. Therefore, when using .Net 4.5 version of Ab3d.DXEngine, you also need to add reference to SharpDX.Mathematics assembly. The following is the list of required references:

      • Ab3d.DXEngine (core classes that can render the 3D scene; assembly revision number 45 or 1045)
      • Ab3d.DXEngine.Wpf (classes that convert existing WPF 3D objects into DXEngine 3D scene; assembly revision number 45 or 1045)
      • SharpDX (core library for the managed DirectX wrapper)
      • SharpDX.Direct3D11 (managed DirectX 11 classes)
      • SharpDX.DXGI (managed DirectX DXGI classes)
      • SharpDX.Mathematics (base math types like Vector3, Matrix, Color3, etc. - those types were moved from core SharpDX library)

   When you are compiling shader hlsl files at runtime, you will also need to reference the SharpDX.D3DCompiler assembly.

3. To show 3D scene defined with Viewport3D with Ab3d.DXEngine, the Viewport3D must be enclosed with DXViewportView control.

   1. In XAML this can be done in two simple steps. First, in the root xaml element add the namespace reference to the Ab3d.DirectX.Controls - for example:
      

      xmlns:dxControls="clr-namespace:Ab3d.DirectX.Controls;assembly=Ab3d.DXEngine.Wpf"

      Then create a new DXViewportView control and copy the existing Viewport3D and its children into the DXViewportView element - for example:

      <dxControls:DXViewportView Name="MainDXViewportView">
          <Viewport3D Name="MainViewport">  
              <!-- existing WPF Viewport3D content -->
          </Viewport3D>  
      <dxControls:DXViewportView>

   2. When your scene is defined in code behind, you can use the following code to initialize DirectX 11 rendering:

       var wpfViewport3D = new Viewport3D();
       var dxViewportView = new DXViewportView();
      
       dxViewportView.Viewport3D = wpfViewport3D;
      
       // Add code to defined 3D objects in wpfViewport3D
      

   After that you can already press F5 and start your application with a brand new DirectX 11 rendering engine.

   But before you begin adding 3D content please do not forget to dispose the DXViewportView.

4. DXViewportView needs to be disposed when it is not used any more.

   DXEngine can allocate a lot of unmanaged resources that need to be manually disposed by calling Dispose method. If you do not dispose the resources, windows will dispose them when you close your application. This means that if your application creates only one Window with one instance of DXViewportView, you do not need to dispose the resources (though it is still teh best practice to call MainDXViewportView.Dispose() when your main window is closed). But if you create more instances of DXViewportView, the resources are not automatically disposed and the memory usage of the process can raise until computer runs out of memory or when the process ends.

   Therefore it is the best to dispose the resources. This can be done in the Unload or Closing event handler for the Window that hosts DXViewportView. When using Unload event, be careful because it can be fired when the control is only hidden - for example for control inside TabControl. Usually it is the best to use Unload event on Window - for example:

   this.Unloaded += (sender, args) => MainDXViewportView.Dispose();

   Calling Dispose on DXViewportView is enough when you are using DXViewportView only with WPF 3D objects. But when you use some advanced DXEngine features and are creating DXEngine objects by yourself (for example LineMaterial, MeshObjectNode, etc.), you need to dispose all the created objects that implement IDisposable (all DXEngine materials, Effects, Mesh objects and SceneNodes). To help yuo collect the objects to dispose, you can use the Ab3d.DirectX.DisposeList. See samples under Customization section or in WinForms project for more info.

To learn more on how to use the DXEngine proceed to the Overview section.