Ab3d.DXEngine Users Guide

 

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 with .NET 4.0 and newer framework and with .NET Core 3.1 and newer.

  2. The first step is to add references to the following libraries:
    • Ab3d.DXEngine (core classes that can render the 3D scene)
    • Ab3d.DXEngine.Wpf (classes that convert existing WPF 3D objects into DXEngine 3D scene)
    • 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)
    This can be done with using the following NuGet packages:

    Instead of using NuGet packages, you can also download the evaluation installer from the downloads web page and then reference installed dlls (this does not include assemblies for .NET CORE).

    In case of using NuGet packages, you can get the Ab3d.DXEngine sample projects from Ab3d.DXEngine.Wpf.Samples on GitHub. When using the installer, the samples will be installed with the libraries.

  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.