Announcing the DirectX 12 Agility SDK!
We’re excited to unveil the DirectX 12 Agility SDK , an update that will allow devs to adopt the newest DirectX 12 graphics features faster than ever before.
With the Agility SDK, developers can now add the newest DirectX 12 features to their games, and gamers can play games with these features without having to upgrade their OS.
Games can use the Agility SDK to light up the latest features on any device with the Windows 10 November 2019 Update or newer. As of this writing of this blog, this already means close to every gamer machine today can run games which use the Agility SDK!
Developers excited about the Agility SDK should check out our Getting Started Guide, Downloads Page and Announcement Talk
Accelerating DirectX Innovation
Historically, the DirectX team used Windows 10 updates to get out our latest features, but game developers told us that they wished that they could add the latest DirectX 12 features to their game without requiring gamers to upgrade their OS.
Could there be a way to get the latest DirectX features up and running on a gamer’s machine, even before they get the latest OS?
We built the DirectX 12 Agility SDK to respond to this very feedback. Here’s what some of our partners had to say:
“Our collaboration with Microsoft on the DirectX 12 Agility SDK enables us to easily implement forward-looking Unreal Engine features, and the new distribution model makes them quickly available to our developer and player communities.”
Nick Penwarden, Vice President, Engineering, Epic Games
With the Agility SDK, all DirectX 12 features, new and old, can run on a huge install base:
“ The DirectX 12 Agility SDK allows us at 343 to be confident that the latest innovation from the DirectX team runs for nearly all of our PC players. ”
Tom Holmes, Engine Architect at 343 Industries
This means that game developers can adopt the latest DirectX 12 features much sooner:
“ The DirectX 12 Agility SDK will allow us to adopt the latest DirectX 12 features faster than ever. We are really excited about what this change means for the future of Forza Tech at Turn 10 and Playground Games. ”
Chris Tector, Studio Software Architect at Turn 10 Studios
What does this mean for gamers?
Put simply, what’s good for developers is good for gamers .
The Agility SDK makes it easier than ever for developers to provide gamers with the best experience from their gaming rig. We’re talking about more games adopting the latest graphics features sooner.
With many game developers not wanting to leave behind gamers on older Windows 10 versions, it used to be that some developers had to make the difficult decision to wait until a version saturates a large enough audience before adopting a feature.
The Agility SDK removes OS rollout as a bottleneck for our latest features to get adopted – gamers can now look forward to the latest features from DirectX getting used sooner than ever before.
What features are we talking about?
We already have our first Agility SDK out, with support for the full DirectX 12 Ultimate feature set and Shader Model 6.6:
- That’s right, many of the DirectX 12 Ultimate features that used to be limited to devices with May 2020 Update , can now run on substantially more gamers’ machines today, since the Agility SDK runs on the November 2019 Update and up!
- Shader Model 6.6 is an update that’s so new that support for it will only roll out with the next Windows 10 OS. It’s the first of many new features that will ship with the Agility SDK model even before the next OS ships.
The Agility SDK is great not just for PC gamers
While the Agility SDK only applies to building PC games, gamers on Xbox will reap the benefits as well. The DirectX team no longer only has one chance to get our latest features out, with the OS. Instead, we get to ship our features to developers whenever we’re ready to, by issuing a new SDK. This means that for the features that exist on Xbox that we can bring to PC and vice and versa, this can happen at roughly the same time.
Developers that have games that run on both platforms are sometimes conscious about feature parity: they don’t want only one segment of their gamers to have a cutting-edge feature. Another issue is that it’s tricky to maintain divergent code paths. In situations where one platform has a feature that the other does not, these developers sometimes must make the tough call to not support the feature, or to wait until it’s on both platforms. With the Agility SDK, we can now remove a big blocker for these devs with cross-platform titles.
All of this means that gamers will see new DirectX features getting adopted sooner than ever.
Getting Started with the Agility SDK
This guide is intended for developers who want to get started developing games that use the Agility SDK. It covers:
Visit the DirectX Landing Page for more resources for DirectX developers.
What is the Agility SDK and how does it work?
The DirectX team used to rely solely on Windows 10 OS Updates to get DirectX feature updates onto gamer machines. Even though shipping with the OS means that all DirectX 12 features eventually reach a large audience of gamers, this also meant that DirectX features were gated on an OS upgrade.
With an OS version often taking take 1-2 years for a given feature to reach a critical mass of users before developers can justify adopting this feature, this meant that OS rollout used to be a bottleneck for the latest DirectX innovation.
With the Agility SDK model, the DirectX team fixes this problem by allowing any application to light up newer DirectX 12 functionality than what’s on a given OS. The Agility SDK model lets this happen while also ensuring that there are no interruptions to existing games that rely on the System32 DirectX 12 runtime, D3D12.dll.
This works through an OS change, where the DirectX team split D3D12.dll into two:
- D3D12.dll, which is now just a thin loader
- D3D12Core.dll, which now contains the bulk of what used to be the old DirectX 12 runtime
For existing games that don’t opt to use the Agility SDK, D3D12.dll simply loads in D3D12Core.dll:
For a developer using the Agility SDK, D3D12.dll can load a newer D3D12Core.dll than the one in System32, one that this developer will include with their app:
The DirectX team is going to carry on shipping updates to DirectX by including the latest version of D3D12Core.dll with each new version of Windows 10.
When an OS has a more recent D3D12Core than what a game shipped with, the OS version of D3D12Core gets loaded instead:
This model means that the DirectX team gets to keep on shipping DirectX 12 updates with the latest Windows 10 OS, while also giving developers who want newer functionality the option to do just that.
It also means that game developers using the Agility SDK don’t have to worry about getting their game using the latest version of DirectX – once they’ve shipped their game, this will happen automatically once later versions of DirectX roll out with the OS.
Developers looking for more detail can find it in the spec.
Setting up your machine
Here’s a handy little checkbox to make sure your machine is ready to start developing:
OS with Agility SDK support | Check |
Drivers with support for the features you’re targeting | Check |
Visual Studio (we recommend VS 2019) | Check |
PIX | Check |
The DirectX Shader Compiler you want to use | Check |
OS with Agility SDK support
Go into Settings > System > About to check your OS Version and Revision Number
In the About menu, scroll down to the section, Windows specifications
OS Version
The number next to Version is your OS Version. As long as this number is equal to or greater than 1909, your machine has support for Agility SDK.
Revision Number
If your OS Version is 1909, 2004 or 20H2, you also want to check your Revision Number.
For subsequent OSes this check will not be necessary.
The number appended to your OS build number, the Revision Number, gets incremented with each KB patch that your OS gets.
- For Windows 10 Version 1909, the revision number should exceed or be equal to .1350 (as in the image above)
- For Windows 10 Version 2004 and 20H2, the revision number should exceed or be equal to .789
More info on the specific KB patches that bring support for the Agility SDK are here and here.
Another check to see if your machine has support for the Agility SDK is to go into your machine’s System32 folder (usually in C:\Windows\System32; you can also type in %systemroot%\system32 into the file explorer).
The existence of D3D12Core.dll in System32 means that your system has received the Agility SDK-enabling loader change explained in the section above.
Note that Windows Server 2022, which is already in preview, has support for the Agility SDK. All subsequent server builds will also have support for the Agility SDK.
See the Troubleshooting section for more info about getting an OS with support for the Agility SDK.
Drivers with support for the features you’re targeting
The DirectX team has been working with our IHV partners to ensure that drivers work as intended with the Agility SDK, lighting up features newer than what’s on a given OS.
As before, developers need to make sure that they use drivers with support for the features they are targeting. For the new features that our first SDK is enabling (the full DirectX 12 Ultimate feature set and Shader Model 6.6), be sure to get:
- A developer driver from AMD; see here to download it.
- For NVIDIA, it’s any driver 466.11 and above, see here to download it
Visual Studio
We recommend using Visual Studio 2019, but Visual 2017 also works. The free Community version works if you don’t already have the Professional or Enterprise editions.
PIX on Windows
PIX, our Graphics debugger, has native support for the Agility SDK, DirectX 12 Ultimate and Shader Model 6.6
Go to Download | PIX on Windows to get the latest version of PIX
The DirectX Shader Compiler you want to use
The Windows 10 SDK already comes with a copy of the DirectX Shader Compiler.
But, if you’re using Shader Model 6.6, you also want to grab the correct DirectX Shader Compiler release, to allow you to compile and run shaders that make use of our latest shader model.
How to use the Agility SDK
This section covers:
1. Install the Agility SDK of your choice from NuGet.org
You now need to grab the Agility SDK of your choice and install it.
Method a: Use Visual Studio’s NuGet UI is for developers who are using stock .vcxproj as their build system, and who want to use Visual Studio’s UI to install an Agility SDK NuGet package.
Method b: Manually include the Agiliy SDK is for developers on a different build system, who cannot use Visual Studio’s built-in NuGet installation UI.
Method c: Extract the contents of the Agility SDK .nupkg is for developers who want to avoid using NuGet.
Method a: Use Visual Studio’s NuGet UI
In Visual Studio, this can be done as follows: right click on your project and go to Manage NuGet Packages. Once here, search for the Agility SDK from nuget.org (type “Microsoft.Direct3D.D3D12” or “DirectX 12 Agility”). Once you’ve found the version you’re looking for, hit install.
As of the writing of this post, there is only one Agility SDK available, but see the Agility SDK Downloads Page for the latest information.
By default the path to components in the Agility SDK (D3D12SDKPath) gets set as “.\D3D12\”. This means that the Agility SDK components needed to build your project will be put in a subdirectory called D3D12, in the same folder as your application exe.
However, you can also right click project and choose properties to set a custom path D3D12SDKPath:
The DirectX team recommends that developers avoid having Agility SDK components in the same directory as their application exe, to avoid mismatching D3D12SDKLayers with the D3D12SDKVersion of D3D12Core.dll (see Known Issues for more detail)
Method b: Manually include the Agility SDK
Developers on a different build system can download our NuGet package and unzip it. To unzip any NuGet package, simply change its extension form .nupkg to .zip before extracting the files.
Other options are to use NuGet to install from nuget.org:
Developers can also use NuGet to install from a folder:
Be sure to place D3D12Core.dll and the other SDK components you want to use into the appropriate app local directory. The code in Set Agility SDK parameters below expects Agility SDK components to be in a folder called D3D12 in the same directory as the application exe, a good option for developers to avoid a known issue.
Method a automatically updates your include path to use new headers. This must be done manually here, i.e. include directory order should have the NuGet include directory before the Windows SDK include directories.
With Method b, we also recommend using the d3d12.lib from the Windows SDK.
Method c: Extract the contents of the Agility SDK .nupkg
Developers who want to extract the contents of any Agility SDK can do so with two PowerShell commands. The first command fetches an Agility SDK NuGet package and saves it as a .zip file. The second command extracts the contents of this zip file.
See below for an example:
Note that this example is grabbing SDK version 1.4.10; be sure to specify the version you are looking to extract. The latest version and information about it can be found on the Downloads Page.
Note that -DestinationPath in the second command specifies that the contents of the package should be extracted to a directory called d3d. Be sure to move D3D12Core.dll to the correct app local directory that you intend to be the D3D12SDKPath (see below).
2. Set Agility SDK parameters
You’re almost ready to build your project, but first you need to register some data to allow the inbox D3D12.dll loader to make its choice about whether it will load the inbox System32 D3D12Core.dll or the app local D3D12Core.dll that you’re using with the Agility SDK.
Specifically, you will need to export constant data via two well-known symbols, D3D12SDKVersion and D3D12SDKPath.
Note that these parameters need to be exported from the main .exe for the process.
D3D12SDKVersion is the SDK version of the D3D12Core.dll from the Agility SDK you are using to build your application.
Note that this will be equal to 4 for our first Agility SDK. This will be incremented with subsequent SDKs; the D3D12SDKVersion of each Agility SDK is noted in the table in the Downloads Page.
Note also that D3D12CreateDevice will fail if the D3D12SDKVersion you export does not match the SDK version of D3D12Core.dll.
D3D12SDKPath is the path to the Agility SDK binaries you are using relative to the application exe.
If you used Visual Studio’s NuGet UI to install the SDK (Method a) and didn’t set a custom D3D12SDKPath, this will be “.\\D3D12\\”
Method a: __declspec(dllexport) keyword
A can export these constants as follows using the __declspec(dllexport) keyword:
Here n corresponds to the D3D12SDKVersion you’re using. For our first Agility SDK, this value is 4.
Method b: Module-definition file
Another option is to export these constants via a .def file:
And then to declare the constants in code as follows:
Here n corresponds to the D3D12SDKVersion you’re using. For our first Agility SDK, this value is 4.
3. Build and ship your game
If you have set and exported these parameters, you should be ready to build your executable.
To ship your game, you must include the D3D12Core.dll you used to build your game and use the same folder structure that you declared with D3D12SDKPath.
Remember to also remove the debug layer (D3D12SDKLayers.dll) from your application’s installer. The DirectX team highly recommends using the debug layer for development, but it’s not necessary to ship a game with it.
Troubleshooting
I went into About and I have an older OS Version or Revision Number
Every Windows 10 OS Version 1909 (November 2019 Update) and above has support for the Agility SDK.
As of the writing of this guide, OSes older than Version 1909 have fallen out of servicing support. We recommend upgrading to an in-service OS not just to get support for the Agility SDK but also to ensure that you’re getting security updates.
See here for more info on Microsoft’s support timeline.
To get onto a more recent OS version and/or to find the latest Windows Updates, go into Settings > Windows Update and click on Check for Updates.
If clicking on Check for Updates does not work on your machine and your machine is managed by an IT department, there’s a chance that your IT department has blocked updates to your machine. If this is the case, please work with your organization’s IT department to get onto a more recent OS.
More info on the specific KB patches that bring support for the redist are here and here.
Note that Windows Server 2022, which is already in preview, has support for the Agility SDK. All subsequent server builds will also have support for the Agility SDK.
Note that the Agility SDK is not supported on OSes before Windows 10.
I hit D3D12_ERROR_INVALID_REDIST – 887e0003 … Missing D3D12GetInterface Export from D3D12Core
This error message means that D3D12Core.dll was not found in the location specified for D3D12SDKPath. Be sure to include a trailing slash!
In the next OS version that Microsoft ships, this error message will be clearer: “Unable to load D3D12Core.dll. Verify D3D12SDKPath is correct.”
I hit D3D12_ERROR_INVALID_REDIST – 887e0003 … D3D12SDKVersion from D3D12Core != requested D3D12SDKVersion
This error message means there’s a mismatch between the D3D12SDKVersion you are requesting and the D3D12SDKVersion of the D3D12Core.dll from the Agility SDK you’ve installed.
You can check the D3D12SDKVersion of the Agility SDK you’ve installed by right-clicking on your project and going into Manage NuGet Packages. The NuGet package minor version number is the same as the D3D12SDKVersion e.g. in 1.4.9, the middle number indicates that D3D12SDKVersion is equal to 4.
This is also embedded in the dll version. Right click on D3D12Core.dll, go to Properties, Details tab, to see the File Version. Again, minor version is the D3D12SDKVersion and will match the NuGet package it came from.
I hit D3D12_ERROR_INVALID_REDIST – 887e0003 …. D3D12 SDKLayers dll does not match the D3D12SDKVersion of D3D12 Core dll
A mismatch between D3D12SDKLayers (the debug layer) and the D3D12SDKVersion of D3D12Core.dll can happen if the System32 D3D12Core.dll is loaded instead of the app local copy of D3D12Core.dll. This issue can be avoided by ensuring that all Agility SDK components are not in the same directory as the application exe, but a subdirectory instead.
I have the correct hardware and exports, but new features are not lighting up as expected
Please be sure to query CheckFeatureSupport if you’re not doing so already. If you have supported hardware for new features you are trying to light up and you aren’t hitting any errors related to D3D12SDKPath or D3D12SDKVersion, be sure to check you have the correct drivers.
I hit another issue
Please let us know! Go to discord.gg/directx to ask questions and/or give us feedback.
Known issues
D3D12SDKPath should not be the same directory as the application exe
If the components in Agility SDK are in the same directory as the application exe, this might cause issues – we recommend putting Agility SDK components in a subdirectory of your application exe directory.
A mismatch between D3D12SDKLayers (the debug layer) and D3D12Core.dll will cause CreateDevice to fail and can happen if the app local D3D12SDKLayers is used when the System32 D3D12Core.dll is loaded.
This is prone to happen if the Agility SDK components are in the same directory as the application exe.
Header Include Order
Headers in the Agility SDK may conflict with the headers from the Windows SDK, depending on include ordering. The DirectX team is working on a fix, but in the meantime please be sure to include Agility SDK headers before you include headers from the Windows 10 SDK.
Common symptoms may include missing D3D_FEATURE_LEVEL_12_2 or any of these shader feature defines:
WACK (Windows App Certification Kit) Support
Agility SDKs do not pass WACK at the moment, but Microsoft is working to enable this.
This means that developers building UWP apps will need to wait until this issue is fixed.
Стал доступен Agility SDK для DirectX 12
Этот набор инструментов позволяет разработчикам использовать новые функции DirectX без необходимости игрокам обновлять Windows. Теперь разработчики игр могут исходить из того, что большинство компьютеров с Windows будут работать со всеми функциями DirectX 12.
Игры могут использовать Agility SDK на системах с обновлением Windows 10 за ноябрь 2019 г. или новее. Разработчики уже могут ознакомиться со стартовым руководством, страницей загрузок.
Раньше команда DirectX использовала обновления Windows 10 для доставки обновлений, но разработчикам игр такой подход не очень нравился. Теперь в этом нет необходимости.
На данный момент уже есть версия Agility SDK с поддержкой полного набора функций DirectX 12 Ultimate и Shader Model 6.6.
Microsoft официально анонсировала DirectX 12 Agility SDK
В прошлом году Microsoft анонсировала DirectX 12 Ultimate API, который позволит играм использовать несколько современных графических функций DirectX 12, таких как DirectX Raytracing (DXR), Variable Rate Shading (VRS), Mesh Shaders и Sampler Feedback. Однако у DX12 Ultimate есть серьезное ограничение. API поддерживается только ПК с Windows с обновлением от мая 2020 года или новее, что серьезно затрудняло скорость принятия современного API, поскольку разработчики не хотели кодировать игры для меньшего числа людей.
В качестве решения этой проблемы Microsoft сегодня выпустила новый DirectX 12 Agility SDK. Этот новый SDK, в отличие от DX12 Ultimate, совместим с компьютерами, в которых все еще используется Windows 10 до ноябрьского обновления 2019 г. По сути, он сделает функции DirectX 12 Ultimate обратно совместимыми со старыми версиями ОС. По словам Microsoft, разработчики довольны этим, поскольку это должно очень помочь с принятием DirectX 12 Ultimate API и сопутствующих ему функций, поскольку, естественно, гораздо больше пользователей использует более старые версии сборки.
Agility SDK полностью совместим с DirectX 12 Ultimate и HLSL Shader Model 6.6. Сегодня была анонсирована Shader Model 6.6, которая предлагает несколько современных функций компиляции шейдеров.