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