SharpDX numbered classes, where do i find their respective documentation/responsibilities?

Question

I'm having a hard time everytime i look at SharpDX code and try to follow DirectX documentation. Is there a place where what each of the numbered classes map to and why they exist is clearly laid out?

I'm talking about things like :

            DXGI.Device
            DXGI.Device1
            DXGI.Device2
            DXGI.Device3
            DXGI.Device4

            SharpDX.Direct3D11.Device
            SharpDX.Direct3D11.Device1
            SharpDX.Direct3D11.Device11On12
            SharpDX.Direct3D11.Device2
            SharpDX.Direct3D11.Device3
            SharpDX.Direct3D11.Device4
            SharpDX.Direct3D11.Device5

            SharpDX.Direct3D11.DeviceContext
            SharpDX.Direct3D11.DeviceContext1
            SharpDX.Direct3D11.DeviceContext2
            SharpDX.Direct3D11.DeviceContext3
            SharpDX.Direct3D11.DeviceContext4

Everytime i start from code i find it seems to be picked by black magic and i have no idea where to go from there, for example i'm using this (from code i found) and i have no idea why it's device3, factory 3 going with swapchain1 on which we queryinterface swapchain2 :

        using (DXGI.Device3 dxgiDevice3 = this.device.QueryInterface<DXGI.Device3>())
        using (DXGI.Factory3 dxgiFactory3 = dxgiDevice3.Adapter.GetParent<DXGI.Factory3>())
        {

            DXGI.SwapChain1 swapChain1 = new DXGI.SwapChain1(dxgiFactory3, this.device, ref swapChainDescription);
            this.swapChain = swapChain1.QueryInterface<DXGI.SwapChain2>();
        }

If full explanation is too large of a the scope of an answer here any link to get me started on figuring out what C++ DX maps to which numbered object and why is most welcome.

In case this matters i'm only interested in DX >= 11, and i'm using SharpDX within an UWP project.

Answer 1

Here you can find about all SharpDx objects, specifically for DXGI you can found here, There you can see the Device mapped to IDXGIDevice. Note the words IDXGIDevice are hyperlink that references to documentation for C++ object. And on this way Device1 and Device2 etc.

You can see that there is a very simple logic here, SharpDx divides the name of the C++ object into Namespace and a class name, For example instead of IDXGIDevice, you get Namespace: DXG and class Name: Device.

In the documentation for each C++ object you can find Requirements. And there is detailed in which operating system you can use the object. As the number is higher, the object will work in a newer operating system. For example, IDXGIDevice1 works under Windows 7, however IDXGIDevice3 works under Windows 8.1 or higher.

Answer 2

SharpDx is a pretty thin wrapper around DirectX, and pretty much everything in DirectX is expressed in SharpDx as a pass-through with some naming and calling conventions to accommodate the .net world.

Real documentation on SharpDx is essentially nonexistent, so you will have to do what everybody else does. If you are starting with something in SharpDx then look directly at the SharpDx API listings and the header files to understand what underlying DirectX functions are being expressed. Once you have the name of the DirectX function, you can read the MSDN documentation to understand how that function works. If you are starting with something in DirectX, then look first at MSDN to understand how it works and how it's named, and then go to the SharpDx API and header files to find out how that function is wrapped (named and exposed) in SharpDx.

For the specific question you ask, SharpDx device numbering identifies the Direct3D version that is being wrapped.

Direct3D 11.1 device ==> ID3D11Device1 ==> SharpDX.Direct3D11.Device1

Direct3D 11.2 device ==> ID3D11Device2 ==> SharpDX.Direct3D11.Device2

Direct3D 11.3 device ==> ID3D11Device3 ==> SharpDX.Direct3D11.Device3

and so on.

Naturally each version has a slightly different ("improved") interface. Lower version numbers will work pretty much anywhere, and higher version numbers include additional functionality that may require something specific from your video card and/or your operating system. You can read about the API for each version in sections found here.

For example, the description of the new methods added to the ID3D11Device5 interface (i.e, what's new since ID3D11Device4) is here. In this case, Device5 adds the ability to create a fence object and to open a handle for a shared fence.

When example code uses a specific device number, it's usually because the code requires some functionality that wasn't there in a previous version of Direct3D. In general you want to use the lowest numbered device (and factory, etc.) possible, because that will permit your code to run on the widest variety of machines and video cards.

If you find example code that creates a SharpDX.Direct3D11.Device1 but doesn't appear to use any methods beyond those in SharpDX.Direct3D11.Device, it's probably for one of two reasons. First, the author may know that a later example will require a method or field that doesn't exist before Direct3D 11.1. Second, the author may know that every video card and operating system capable of running the example at all will be capable of running Direct3D 11.1.

For a person just starting out, I would suggest you just stick with Direct3D (and Direct2D) version 11.1, thus DXGI.Device1, SharpDX.Direct3D11.Device1 and SharpDX.Direct3D11.DeviceContext1. These are likely to run on any machine you'll encounter. Only increase the version number if you actually need some functionality that doesn't appear in that version.

One additional hint: if you read a thread about some Direct3D or Direct2D functionality and you can't seem to find it anywhere in SharpDx, look at the Direct3D API to see what version number first contains that functionality. Then go through the SharpDx API (or better yet the header files) for that version until you see a similarly named element. It may be wrapped in an unexpected way, but AFAIK it's all exposed, even when you have a hard time finding it.