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:

Ab3d.DXEngine can be used with .NET 4.0 and newer framework, .NET Core 3.1 and .NET 5.0 or newer.
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 by 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.
To use Ab3d.DXEngine to show 3D scene defined by Viewport3D, the Viewport3D must be enclosed by the 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">  
        
    </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.
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.
Check that mouse events are correctly assigned.

When using only Ab3d.PowerToys, then the Viewport3D control can be the source of mouse events for MouseCameraController, hit testing and for ModelMoverVisual3D, ModelRotatorVisual3D and ModelScalarVisual3D. But because the Viewport3D will not be actually visible when it is shown by DXViewportView, the Viewport3D cannot be used as a source for mouse events.

Therefore please check that MouseCameraController and hit testing use DXViewportView or its parent control for source of mouse events. See the samples that come with Ab3d.DXEngine for more. There usually a parent Border that needs to have Background property set is usually used as an event source.

For example, for MouseCameraController that is defined in XAML, this is setup as:
```
<Border Name="ViewportBorder" Background="White">
    <dxControls:DXViewportView Name="MainDXViewportView" PresentationType="DirectXImage" BackgroundColor="Transparent">
        <Viewport3D Name="MainViewport">
            
        </Viewport3D>
    </dxControls:DXViewportView>
</Border>

<ab3d:MouseCameraController Name="MouseCameraController1" 
                            RotateCameraConditions="RightMouseButtonPressed"
                            MoveCameraConditions="RightMouseButtonPressed, ControlKey"
                            TargetCamera="{Binding ElementName=Camera1}" 
                            EventsSourceElement="{Binding ElementName=ViewportBorder}"/>
```
When using ModelMoverVisual3D, ModelRotatorVisual3D and ModelScalarVisual3D, then you need to use the Ab3d.Utilities.EventManager3D to support mouse events. See the code comments in the PowerToysOther/ModelMoverInsideObjectSample.xaml.cs file that comes with Ab3d.DXEngine samples.

See also the samples in the Other Ab3d.PowerToys samples section of Ab3d.DXEngine samples for more information about using Ab3d.PowerToys by the Ab3d.DXEngine.
Rendering you existing 3D scene by Ab3d.DXEngine should already provide a massive performance increase and render quality improvement.

To be able to render even more 3D objects, consider using object instancing or some other advanced techniques that are available only when using Ab3d.DXEngine. See Extreme performance section of Ab3d.DXEngine samples for more information.

To further improve rendering quality, you can use super-sampling (produces super smooth 3D lines), PBR materials (Physically-Based Rendering materials), advanced transparency rendering techniques, etc. See Improved visuals section of Ab3d.DXEngine samples for more information.

To improve initialization time, you can also convert some Visual3D based 3D objects (from Ab3d.PowerToys or WPF 3D) into low level DXEngine SceneNode objects. See Advanced Ab3d.DXEngine usage section of Ab3d.DXEngine samples for more information.

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