Custom DirectX Agility SDK Configuration

The DX backend can load a custom Agility SDK (e.g., SM 6.9 / SDK 1.619+) without modifying the source, by subclassing DirectXDeviceConfigExt at runtime.

Overview

The DX backend exports D3D12SDKVersion and D3D12SDKPath symbols that the DirectX 12 runtime looks up to locate the Agility SDK. By default, these use the bundled headers (LCAgilitySDK/, D3D12_PREVIEW_SDK_VERSION = 717) and path (.\\D3D12\\). You can override both at device creation time via the extension API.

Prerequisites

Download a custom Agility SDK release from Microsoft’s GitHub releases.
Extract the archive to a directory (e.g. C:/agility-sdk-619/). The directory should contain at least:
- D3D12Core.dll
- d3d12SDKVersion.h (or equivalent headers)

Runtime Configuration via Extension API

Provide a custom Agility SDK version and path at device creation time by subclassing DirectXDeviceConfigExt.

Step 1: Create a custom extension class

#include <luisa/backends/ext/dx_config_ext.h>

using namespace luisa::compute;

class MyAgilitySDKConfig : public DirectXDeviceConfigExt {
public:
    // Return a custom SDK version (0 = use default)
    [[nodiscard]] uint32_t GetSDKVersion() const noexcept override {
        return 619;  // SM 6.9 Agility SDK version
    }

    // Return a custom SDK DLL path (empty = use default ".\\D3D12\\")
    [[nodiscard]] luisa::string_view GetSDKPath() const noexcept override {
        return "C:/agility-sdk-619/";
    }
};

Step 2: Pass the extension when creating the device

#include <luisa/luisa-compute.h>
#include <luisa/backends/ext/dx_config_ext.h>

int main() {
    Context context{};
    auto ext = luisa::make_unique<MyAgilitySDKConfig>();
    DeviceConfig config{};
    config.extension = std::move(ext);
    auto device = context.create_device("dx", &config);
    // ...
}

How it works

During Device construction, GetSDKVersion() and GetSDKPath() are queried from the extension.
The exported D3D12SDKVersion and D3D12SDKPath symbols are updated before CreateDXGIFactory2 / D3D12CreateDevice is called.
The DirectX runtime picks up the custom DLLs from the specified path.

The override happens only when the extension returns non-zero version / non-empty path; default values are preserved otherwise.

Header Compatibility

When using a newer Agility SDK (e.g., version 619), the bundled headers (LCAgilitySDK/d3d12.h, SDK version 616, preview 717) may not match. Options:

Use bundled headers (default): Works if the preview version (717) contains the definitions you need. Most SM 6.9 definitions are already present.
Provide your own headers: Place a custom d3d12.h alongside the SDK DLLs and adjust include paths manually.

Verification

Run your application that uses MyAgilitySDKConfig (see example above). The device will be created with the custom SDK version and path.