DOCSEARCHbyAlgolia
Submit Docs

DirectX Headers

repository·main·Indexed 20 days ago

https://github.com/microsoft/directx-headers

Official Direct3D 12 headers under the MIT license, including core D3D12 headers, d3dx12.h helper files, and specialized support for Windows Subsystem for Linux (WSL) environments. Provides integration methods for CMake, Meson, vcpkg, and NuGet, as well as shims for D3D12 ABI requirements and GUID consistency between Windows and WSL.

Tokens
808
Snippets
0
Records
5
Agent score
23%

What's inside DirectX Headers

  1. Understand the DirectX Headers directory structure

    main

    The repository is organized as follows:

    • /include/directx: Core D3D12 headers and the d3dx12.h helper.
    • /include/wsl: Shims for including D3D12 headers in a Linux/WSL build environment.
    • /include/dxguids: Headers enabling consistent use of uuidof<T>() between Windows and WSL.
    • /src/dxguids.cpp: A replacement for dxguid.lib on Windows, or a translation unit for defining GUIDs on WSL without multiple definitions.
    • /: Contains CMake and Meson build files for integration.
    • /test: CMake/Meson projects for validating the headers.

  2. Use DirectX Headers on WSL (Linux)

    main

    WSL support is intended specifically for frameworks providing hardware acceleration for Linux graphics/compute APIs in a WSL2 environment. It is not intended for general-purpose application development and is only available for 64-bit binaries.

    Key Differences in WSL

    The headers in /include/wsl provide alternative definitions for types to match the D3D12 ABI requirements on Linux:

    • LONG/ULONG: These are defined as 8 bytes (on Linux, long is typically 8 bytes, whereas on 64-bit Windows it is 4 bytes).
    • WCHAR/WCSTR: These use the native 4-byte Linux wchar_t to allow compatibility with the system C library for string manipulation.

    Handling Win32 Handles

    When an API expects a HANDLE (which is void* on Windows), you should use reinterpret_cast<HANDLE>(fd) with the appropriate Linux file descriptor:

    • For ID3D12Fence::SetEventOnCompletion, use an eventfd.
    • For shared resources, use an opaque file descriptor.

  3. Configure include ordering for Windows development

    main

    When using these headers on Windows, they may conflict with the standard Windows SDK headers. To prevent the Windows SDK headers from defining include guards first and blocking these headers, follow these two rules:

    1. Add the directx-headers include directory to your project before the Windows SDK include directories.
    2. Include these headers before other graphics headers from the Windows SDK (for example, before d3d11.h).

  4. Integrate DirectX Headers into your project

    main

    You can consume the DirectX headers using several methods depending on your build system:

    • Manual: Copy the headers to a local directory and add that directory to your project's include paths.
    • CMake Subproject: Add the repository as a subdirectory (e.g., via git submodule) and use add_subdirectory(). You can then link against the DirectX-Headers and/or DirectX-Guids targets.
    • Installed CMake: Use find_package() to locate the installed headers and link against the DirectX-Headers and DirectX-Guids targets.
    • CMake FetchContent: Use FetchContent (CMake 3.11+) to pull the library directly from Git.
    • Meson: Add the project as a subproject/wrap and use subproject or dependency to consume it.
    • vcpkg: Use the available vcpkg port.
    • NuGet: Download the DirectX 12 Agility SDK from NuGet.org.

  5. Use the WRL Client stub for WSL compatibility

    main
    When developing for Windows Subsystem for Linux (WSL), including certain DirectX headers like d3dx12.h may require the presence of WRL (Windows Runtime Library) Client types. This stub provides the necessary compatibility layer by including <wsl/wrladapter.h>, which satisfies the dependencies required by the DirectX headers in a Linux environment.