1================================= 2User Guide for the DirectX Target 3================================= 4 5.. warning:: 6 Disclaimer: The DirectX backend is experimental and under active development. 7 It is not yet feature complete or ready to be used outside of experimental or 8 demonstration contexts. 9 10.. contents:: 11 :local: 12 13.. toctree:: 14 :hidden: 15 16 DirectX/DXContainer 17 DirectX/DXILArchitecture 18 DirectX/DXILOpTableGenDesign 19 DirectX/DXILResources 20 21Introduction 22============ 23 24The DirectX target implements the DirectX programmability interfaces. These 25interfaces are documented in the `DirectX Specifications. <https://github.com/Microsoft/DirectX-Specs>`_ 26 27Initially the backend is aimed at supporting DirectX 12, and support for DirectX 2811 is planned at a later date. 29 30The DirectX backend is currently experimental and is not shipped with any 31release builds of LLVM tools. To enable building the DirectX backend locally add 32``DirectX`` to the ``LLVM_EXPERIMENTAL_TARGETS_TO_BUILD`` CMake option. For more 33information on building LLVM see the :doc:`CMake` documentation. 34 35.. _dx-target-triples: 36 37Target Triples 38============== 39 40At present the DirectX target only supports the ``dxil`` architecture, which 41generates code for the 42`DirectX Intermediate Language. <https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst>`_ 43 44In addition to target architecture, the DirectX backend also needs to know the 45target runtime version and pipeline stage. These are expressed using the OS and 46Environment triple component. 47 48Presently the DirectX backend requires targeting the ``shadermodel`` OS, and 49supports versions 6.0+ (at time of writing the latest announced version is 6.7). 50 51.. table:: DirectX Environments 52 53 ================== ======================================================== 54 Environment Description 55 ================== ======================================================== 56 ``pixel`` Pixel shader 57 ``vertex`` Vertex shader 58 ``geometry`` Geometry shader 59 ``hull`` Hull shader (tesselation) 60 ``domain`` Domain shader (tesselation) 61 ``compute`` Compute kernel 62 ``library`` Linkable ``dxil`` library 63 ``raygeneration`` Ray generation (ray tracing) 64 ``intersection`` Ray intersection (ray tracing) 65 ``anyhit`` Ray any collision (ray tracing) 66 ``closesthit`` Ray closest collision (ray tracing) 67 ``miss`` Ray miss (ray tracing) 68 ``callable`` Callable shader (ray tracing) 69 ``mesh`` Mesh shader 70 ``amplification`` Amplification shader 71 ================== ======================================================== 72 73Output Binaries 74=============== 75 76The DirectX runtime APIs read a file format based on the 77`DirectX Specification. <https://github.com/Microsoft/DirectX-Specs>`_. In 78different codebases the file format is referred to by different names 79(specifically ``DXBC`` and ``DXILContainer``). Since the format is used to store 80both ``DXBC`` and ``DXIL`` outputs, and the ultimate goal is to support both as 81code generation targets in LLVM, the LLVM codebase uses a more neutral name, 82``DXContainer``. 83 84The ``DXContainer`` format is sparsely documented in the functional 85specification, but a reference implementation exists in the 86`DirectXShaderCompiler. <https://github.com/microsoft/DirectXShaderCompiler>`_. 87The format is documented in the LLVM project docs as well (see 88:doc:`DirectX/DXContainer`). 89 90Support for generating ``DXContainer`` files in LLVM, is being added to the LLVM 91MC layer for object streamers and writers, and to the Object and ObjectYAML 92libraries for testing and object file tooling. 93 94For ``dxil`` targeting, bitcode emission into ``DXContainer`` files follows a 95similar model to the ``-fembed-bitcode`` flag supported by clang for other 96targets. 97