llvm/docs/DirectXUsage.rst

   1 =================================
   2 User 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
  21 Introduction
  22 ============
  23
  24 The DirectX target implements the DirectX programmability interfaces. These
  25 interfaces are documented in the `DirectX Specifications. <https://github.com/Microsoft/DirectX-Specs>`_
  26
  27 Initially the backend is aimed at supporting DirectX 12, and support for DirectX
  28 11 is planned at a later date.
  29
  30 The DirectX backend is currently experimental and is not shipped with any
  31 release 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
  33 information on building LLVM see the :doc:`CMake` documentation.
  34
  35 .. _dx-target-triples:
  36
  37 Target Triples
  38 ==============
  39
  40 At present the DirectX target only supports the ``dxil`` architecture, which
  41 generates code for the
  42 `DirectX Intermediate Language. <https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/DXIL.rst>`_
  43
  44 In addition to target architecture, the DirectX backend also needs to know the
  45 target runtime version and pipeline stage. These are expressed using the OS and
  46 Environment triple component.
  47
  48 Presently the DirectX backend requires targeting the ``shadermodel`` OS, and
  49 supports 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
  73 Output Binaries
  74 ===============
  75
  76 The DirectX runtime APIs read a file format based on the
  77 `DirectX Specification. <https://github.com/Microsoft/DirectX-Specs>`_. In
  78 different codebases the file format is referred to by different names
  79 (specifically ``DXBC`` and ``DXILContainer``). Since the format is used to store
  80 both ``DXBC`` and ``DXIL`` outputs, and the ultimate goal is to support both as
  81 code generation targets in LLVM, the LLVM codebase uses a more neutral name,
  82 ``DXContainer``.
  83
  84 The ``DXContainer`` format is sparsely documented in the functional
  85 specification, but a reference implementation exists in the
  86 `DirectXShaderCompiler. <https://github.com/microsoft/DirectXShaderCompiler>`_.
  87 The format is documented in the LLVM project docs as well (see
  88 :doc:`DirectX/DXContainer`).
  89
  90 Support for generating ``DXContainer`` files in LLVM, is being added to the LLVM
  91 MC layer for object streamers and writers, and to the Object and ObjectYAML
  92 libraries for testing and object file tooling.
  93
  94 For ``dxil`` targeting, bitcode emission into ``DXContainer`` files follows a
  95 similar model to the ``-fembed-bitcode`` flag supported by clang for other
  96 targets.