// Copyright (c) 2017-2024, The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

include::{generated}/meta/XR_KHR_D3D11_enable.adoc[]

*Last Modified Date*::
   2018-11-16
*IP Status*::
    No known IP claims.
*Contributors*::
    Bryce Hutchings, Microsoft +
    Paul Pedriana, Oculus +
    Mark Young, LunarG +
    Minmin Gong, Microsoft +
    Matthieu Bucchianeri, Microsoft

*Overview*

This extension enables the use of the D3D11 graphics API in an OpenXR
runtime.
Without this extension, the OpenXR runtime may not be able to use any D3D11
swapchain images.

This extension provides the mechanisms necessary for an application to
generate a valid slink:XrGraphicsBindingD3D11KHR structure in order to
create a D3D11-based slink:XrSession.
Note that during this process the application is responsible for creating
all the required D3D11 objects, including a graphics device to be used for
rendering.

This extension also provides mechanisms for the application to interact with
images acquired by calling flink:xrEnumerateSwapchainImages.

In order to expose the structures, types, and functions of this extension,
you must: define dlink:XR_USE_GRAPHICS_API_D3D11 before including the OpenXR
platform header `openxr_platform.h`, in all portions of your library or
application that include it.
*Swapchain Flag Bits*

All elink:XrSwapchainUsageFlags values passed in a session created using
slink:XrGraphicsBindingD3D11KHR must: be interpreted as follows by the
runtime, so that the returned swapchain images used by the application may
be used as if they were created with the corresponding D3D11_BIND_FLAG
flags.
The runtime may: set additional bind flags but must: not restrict usage.

[cols=2*,options=header]
|===
| elink:XrSwapchainUsageFlagBits
| Corresponding D3D11 bind flag bits

| ename:XR_SWAPCHAIN_USAGE_COLOR_ATTACHMENT_BIT
| `D3D11_BIND_RENDER_TARGET`

| ename:XR_SWAPCHAIN_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT
| `D3D11_BIND_DEPTH_STENCIL`

| ename:XR_SWAPCHAIN_USAGE_UNORDERED_ACCESS_BIT
| `D3D11_BIND_UNORDERED_ACCESS`

| ename:XR_SWAPCHAIN_USAGE_TRANSFER_SRC_BIT
| _ignored_

| ename:XR_SWAPCHAIN_USAGE_TRANSFER_DST_BIT
| _ignored_

| ename:XR_SWAPCHAIN_USAGE_SAMPLED_BIT
| `D3D11_BIND_SHADER_RESOURCE`

| ename:XR_SWAPCHAIN_USAGE_MUTABLE_FORMAT_BIT
| _ignored_

| ename:XR_SWAPCHAIN_USAGE_INPUT_ATTACHMENT_BIT_KHR
  (Added by apiext:XR_KHR_swapchain_usage_input_attachment_bit and only available when that extension is enabled)
| _ignored_

|===

All D3D11 swapchain textures are created with D3D11_USAGE_DEFAULT usage.

*New Object Types*

*New Flag Types*

*New Enum Constants*

elink:XrStructureType enumeration is extended with:

* ename:XR_TYPE_GRAPHICS_REQUIREMENTS_D3D11_KHR
* ename:XR_TYPE_GRAPHICS_BINDING_D3D11_KHR
* ename:XR_TYPE_SWAPCHAIN_IMAGE_D3D11_KHR

*New Enums*

*New Structures*

The following structures are provided to supply supporting runtimes the
necessary information required to work with the D3D11 API executing on
certain operating systems.

[open,refpage='XrGraphicsBindingD3D11KHR',type='structs',desc='The graphics binding structure to be passed at session creation to use D3D11',xrefs='xrCreateSession']
--
The slink:XrGraphicsBindingD3D11KHR structure is defined as:

include::{generated}/api/structs/XrGraphicsBindingD3D11KHR.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:device is a pointer to a valid sname:ID3D11Device to use.
****

When creating a D3D11-backed slink:XrSession, the application will provide a
pointer to an slink:XrGraphicsBindingD3D11KHR in the
slink:XrSessionCreateInfo::pname:next field of structure passed to
flink:xrCreateSession.
The D3D11 device specified in slink:XrGraphicsBindingD3D11KHR::pname:device
must: be created in accordance with the requirements retrieved through
flink:xrGetD3D11GraphicsRequirementsKHR, otherwise flink:xrCreateSession
must: return ename:XR_ERROR_GRAPHICS_DEVICE_INVALID.

include::{generated}/validity/structs/XrGraphicsBindingD3D11KHR.adoc[]
--

[open,refpage='XrSwapchainImageD3D11KHR',type='structs',desc='D3D11-specific swapchain image structure',xrefs='XrSwapchainImageBaseHeader']
--
The slink:XrSwapchainImageD3D11KHR structure is defined as:

include::{generated}/api/structs/XrSwapchainImageD3D11KHR.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:texture is a pointer to a valid sname:ID3D11Texture2D to use.
****

If a given session was created with slink:XrGraphicsBindingD3D11KHR, the
following conditions must: apply.

* Calls to flink:xrEnumerateSwapchainImages on an slink:XrSwapchain in that
  session must: return an array of slink:XrSwapchainImageD3D11KHR
  structures.
* Whenever an OpenXR function accepts an slink:XrSwapchainImageBaseHeader
  pointer as a parameter in that session, the runtime must: also accept a
  pointer to an slink:XrSwapchainImageD3D11KHR.

The OpenXR runtime must: interpret the top-left corner of the swapchain
image as the coordinate origin unless specified otherwise by extension
functionality.

The OpenXR runtime must: interpret the swapchain images in a clip space of
positive Y pointing up, near Z plane at 0, and far Z plane at 1.

include::{generated}/validity/structs/XrSwapchainImageD3D11KHR.adoc[]
--

[open,refpage='XrGraphicsRequirementsD3D11KHR',type='structs',desc='D3D11 feature level and LUID requirements',xrefs='xrGetD3D11GraphicsRequirementsKHR']
--
The slink:XrGraphicsRequirementsD3D11KHR structure is defined as:

include::{generated}/api/structs/XrGraphicsRequirementsD3D11KHR.adoc[]

.Member Descriptions
****
* pname:type is the elink:XrStructureType of this structure.
* pname:next is code:NULL or a pointer to the next structure in a structure
  chain.
  No such structures are defined in core OpenXR or this extension.
* pname:adapterLuid identifies what graphics device needs to be used.
* pname:minFeatureLevel is the minimum feature level that the D3D11 device
  must be initialized with.
****

slink:XrGraphicsRequirementsD3D11KHR is populated by
flink:xrGetD3D11GraphicsRequirementsKHR.

include::{generated}/validity/structs/XrGraphicsRequirementsD3D11KHR.adoc[]
--

*New Functions*

Some computer systems may have multiple graphics devices, each of which may
have independent external display outputs.
XR systems that connect to such graphics devices are typically connected to
a single device.
Applications need to know what graphics device the XR system is connected to
so that they can use that graphics device to generate XR images.

[open,refpage='xrGetD3D11GraphicsRequirementsKHR',type='protos',desc='Retrieve the D3D11 feature level and graphics device requirements for an instance and system',xrefs='XrGraphicsRequirementsD3D11KHR xrCreateSession']
--
To retrieve the D3D11 feature level and graphics device for an instance and
system, call:

include::{generated}/api/protos/xrGetD3D11GraphicsRequirementsKHR.adoc[]

.Parameter Descriptions
****
* pname:instance is an slink:XrInstance handle previously created with
  flink:xrCreateInstance.
* pname:systemId is an basetype:XrSystemId handle for the system which will
  be used to create a session.
* pname:graphicsRequirements is the slink:XrGraphicsRequirementsD3D11KHR
  output structure.
****

The flink:xrGetD3D11GraphicsRequirementsKHR function identifies to the
application what graphics device (Windows LUID) needs to be used and the
minimum feature level to use.
The runtime must: return ename:XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING
(ename:XR_ERROR_VALIDATION_FAILURE may: be returned due to legacy behavior)
on calls to flink:xrCreateSession if flink:xrGetD3D11GraphicsRequirementsKHR
has not been called for the same pname:instance and pname:systemId.
The LUID and feature level that flink:xrGetD3D11GraphicsRequirementsKHR
returns must: be used to create the sname:ID3D11Device that the application
passes to flink:xrCreateSession in the slink:XrGraphicsBindingD3D11KHR.

include::{generated}/validity/protos/xrGetD3D11GraphicsRequirementsKHR.adoc[]
--

*Issues*

*Version History*

* Revision 1, 2018-05-07 (Mark Young)
** Initial draft
* Revision 2, 2018-06-21 (Bryce Hutchings)
** Split `XR_KHR_D3D_enable` into `XR_KHR_D3D11_enable`
** Rename and expand `xrGetD3DGraphicsDeviceKHR` functionality to
   `xrGetD3D11GraphicsRequirementsKHR`
* Revision 3, 2018-11-15 (Paul Pedriana)
** Specified the swapchain texture coordinate origin.
* Revision 4, 2018-11-16 (Minmin Gong)
** Specified Y direction and Z range in clip space
* Revision 5, 2020-08-06 (Bryce Hutchings)
** Added new `XR_ERROR_GRAPHICS_REQUIREMENTS_CALL_MISSING` error code
* Revision 8, 2021-09-09 (Bryce Hutchings)
** Document mapping for `XrSwapchainUsageFlags`
* Revision 9, 2021-12-28 (Matthieu Bucchianeri)
** Added missing `XR_ERROR_GRAPHICS_DEVICE_INVALID` error condition
