Include/OVR_CAPI_D3D.h

   1 /********************************************************************************/ /**\r
   2  \file      OVR_CAPI_D3D.h\r
   3  \brief     D3D specific structures used by the CAPI interface.\r
   4  \copyright Copyright 2014-2016 Oculus VR, LLC All Rights reserved.\r
   5  ************************************************************************************/\r
   6 \r
   7 #ifndef OVR_CAPI_D3D_h\r
   8 #define OVR_CAPI_D3D_h\r
   9 \r
  10 #include "OVR_CAPI.h"\r
  11 #include "OVR_Version.h"\r
  12 \r
  13 \r
  14 #if defined(_WIN32)\r
  15 #include <unknwn.h>\r
  16 #include <guiddef.h>\r
  17 \r
  18 #if !defined(OVR_EXPORTING_CAPI)\r
  19 \r
  20 //-----------------------------------------------------------------------------------\r
  21 // ***** Direct3D Specific\r
  22 \r
  23 /// Create Texture Swap Chain suitable for use with Direct3D 11 and 12.\r
  24 ///\r
  25 /// \param[in]  session Specifies an ovrSession previously returned by ovr_Create.\r
  26 /// \param[in]  d3dPtr Specifies the application's D3D11Device to create resources with\r
  27 ///             or the D3D12CommandQueue which must be the same one the application renders\r
  28 ///             to the eye textures with.\r
  29 /// \param[in]  desc Specifies requested texture properties. See notes for more info\r
  30 ///             about texture format.\r
  31 /// \param[in]  bindFlags Specifies what ovrTextureBindFlags the application requires\r
  32 ///             for this texture chain.\r
  33 /// \param[out] out_TextureSwapChain Returns the created ovrTextureSwapChain, which will\r
  34 ///             be valid upon a successful return value, else it will be NULL.\r
  35 ///             This texture chain must be eventually destroyed via ovr_DestroyTextureSwapChain\r
  36 ///             before destroying the session with ovr_Destroy.\r
  37 ///\r
  38 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use\r
  39 ///         ovr_GetLastErrorInfo to get more information.\r
  40 ///\r
  41 /// \note The texture format provided in \a desc should be thought of as the format the\r
  42 ///       distortion-compositor will use for the ShaderResourceView when reading the contents of\r
  43 ///       the texture. To that end, it is highly recommended that the application requests texture\r
  44 //        swapchain formats that are in sRGB-space (e.g. OVR_FORMAT_R8G8B8A8_UNORM_SRGB)\r
  45 ///       as the compositor does sRGB-correct rendering. As such, the compositor relies on the\r
  46 ///       GPU's hardware sampler to do the sRGB-to-linear conversion. If the application still\r
  47 ///       prefers to render to a linear format (e.g. OVR_FORMAT_R8G8B8A8_UNORM) while handling the\r
  48 ///       linear-to-gamma conversion via HLSL code, then the application must still request the\r
  49 ///       corresponding sRGB format and also use the \a ovrTextureMisc_DX_Typeless flag in the\r
  50 ///       ovrTextureSwapChainDesc's Flag field. This will allow the application to create\r
  51 ///       a RenderTargetView that is the desired linear format while the compositor continues to\r
  52 ///       treat it as sRGB. Failure to do so will cause the compositor to apply unexpected gamma\r
  53 ///       conversions leading to gamma-curve artifacts. The \a ovrTextureMisc_DX_Typeless\r
  54 ///       flag for depth buffer formats (e.g. OVR_FORMAT_D32_FLOAT) is ignored as they are always\r
  55 ///       converted to be typeless.\r
  56 ///\r
  57 /// \see ovr_GetTextureSwapChainLength\r
  58 /// \see ovr_GetTextureSwapChainCurrentIndex\r
  59 /// \see ovr_GetTextureSwapChainDesc\r
  60 /// \see ovr_GetTextureSwapChainBufferDX\r
  61 /// \see ovr_DestroyTextureSwapChain\r
  62 ///\r
  63 OVR_PUBLIC_FUNCTION(ovrResult)\r
  64 ovr_CreateTextureSwapChainDX(\r
  65     ovrSession session,\r
  66     IUnknown* d3dPtr,\r
  67     const ovrTextureSwapChainDesc* desc,\r
  68     ovrTextureSwapChain* out_TextureSwapChain);\r
  69 \r
  70 /// Get a specific buffer within the chain as any compatible COM interface (similar to\r
  71 /// QueryInterface)\r
  72 ///\r
  73 /// \param[in]  session Specifies an ovrSession previously returned by ovr_Create.\r
  74 /// \param[in]  chain Specifies an ovrTextureSwapChain previously returned\r
  75 ///             by ovr_CreateTextureSwapChainDX\r
  76 /// \param[in]  index Specifies the index within the chain to retrieve.\r
  77 ///             Must be between 0 and length (see ovr_GetTextureSwapChainLength),\r
  78 ///             or may pass -1 to get the buffer at the CurrentIndex location. (Saving a call to\r
  79 ///             GetTextureSwapChainCurrentIndex)\r
  80 /// \param[in]  iid Specifies the interface ID of the interface pointer to query the buffer for.\r
  81 /// \param[out] out_Buffer Returns the COM interface pointer retrieved.\r
  82 ///\r
  83 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use\r
  84 ///         ovr_GetLastErrorInfo to get more information.\r
  85 ///\r
  86 /// <b>Example code</b>\r
  87 ///     \code{.cpp}\r
  88 ///         ovr_GetTextureSwapChainBufferDX(session, chain, 0, IID_ID3D11Texture2D, &d3d11Texture);\r
  89 ///         ovr_GetTextureSwapChainBufferDX(session, chain, 1, IID_PPV_ARGS(&dxgiResource));\r
  90 ///     \endcode\r
  91 ///\r
  92 OVR_PUBLIC_FUNCTION(ovrResult)\r
  93 ovr_GetTextureSwapChainBufferDX(\r
  94     ovrSession session,\r
  95     ovrTextureSwapChain chain,\r
  96     int index,\r
  97     IID iid,\r
  98     void** out_Buffer);\r
  99 \r
 100 /// Create Mirror Texture which is auto-refreshed to mirror Rift contents produced by this\r
 101 /// application.\r
 102 ///\r
 103 /// A second call to ovr_CreateMirrorTextureWithOptionsDX for a given ovrSession before destroying\r
 104 /// the first one is not supported and will result in an error return.\r
 105 ///\r
 106 /// \param[in]  session Specifies an ovrSession previously returned by ovr_Create.\r
 107 /// \param[in]  d3dPtr Specifies the application's D3D11Device to create resources with\r
 108 ///             or the D3D12CommandQueue which must be the same one the application renders to\r
 109 ///             the textures with.\r
 110 /// \param[in]  desc Specifies requested texture properties.\r
 111 ///             See notes for more info about texture format.\r
 112 /// \param[out] out_MirrorTexture Returns the created ovrMirrorTexture, which will be valid upon a\r
 113 ///             successful return value, else it will be NULL.\r
 114 ///             This texture must be eventually destroyed via ovr_DestroyMirrorTexture before\r
 115 ///             destroying the session with ovr_Destroy.\r
 116 ///\r
 117 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use\r
 118 ///         ovr_GetLastErrorInfo to get more information.\r
 119 ///\r
 120 /// \note The texture format provided in \a desc should be thought of as the format the compositor\r
 121 ///       will use for the RenderTargetView when writing into mirror texture. To that end, it is\r
 122 ///       highly recommended that the application requests a mirror texture format that is\r
 123 ///       in sRGB-space (e.g. OVR_FORMAT_R8G8B8A8_UNORM_SRGB) as the compositor does sRGB-correct\r
 124 ///       rendering. If however the application wants to still read the mirror texture as a linear\r
 125 ///       format (e.g. OVR_FORMAT_R8G8B8A8_UNORM) and handle the sRGB-to-linear conversion in\r
 126 ///       HLSL code, then it is recommended the application still requests an sRGB format and also\r
 127 ///       use the \a ovrTextureMisc_DX_Typeless flag in the ovrMirrorTextureDesc's Flags field.\r
 128 ///       This will allow the application to bind a ShaderResourceView that is a linear format\r
 129 ///       while the compositor continues to treat is as sRGB. Failure to do so will cause the\r
 130 ///       compositor to apply unexpected gamma conversions leading to gamma-curve artifacts.\r
 131 ///\r
 132 ///\r
 133 /// <b>Example code</b>\r
 134 ///     \code{.cpp}\r
 135 ///         ovrMirrorTexture     mirrorTexture = nullptr;\r
 136 ///         ovrMirrorTextureDesc mirrorDesc = {};\r
 137 ///         mirrorDesc.Format = OVR_FORMAT_R8G8B8A8_UNORM_SRGB;\r
 138 ///         mirrorDesc.Width  = mirrorWindowWidth;\r
 139 ///         mirrorDesc.Height = mirrorWindowHeight;\r
 140 ///         ovrResult result = ovr_CreateMirrorTextureWithOptionsDX(session, d3d11Device,\r
 141 ///         &mirrorDesc, &mirrorTexture);\r
 142 ///         [...]\r
 143 ///         // Destroy the texture when done with it.\r
 144 ///         ovr_DestroyMirrorTexture(session, mirrorTexture);\r
 145 ///         mirrorTexture = nullptr;\r
 146 ///     \endcode\r
 147 ///\r
 148 /// \see ovr_GetMirrorTextureBufferDX\r
 149 /// \see ovr_DestroyMirrorTexture\r
 150 ///\r
 151 OVR_PUBLIC_FUNCTION(ovrResult)\r
 152 ovr_CreateMirrorTextureWithOptionsDX(\r
 153     ovrSession session,\r
 154     IUnknown* d3dPtr,\r
 155     const ovrMirrorTextureDesc* desc,\r
 156     ovrMirrorTexture* out_MirrorTexture);\r
 157 \r
 158 /// Deprecated. Use ovr_CreateMirrorTextureWithOptionsDX instead\r
 159 ///\r
 160 /// Same as ovr_CreateMirrorTextureWithOptionsDX except doesn't use ovrMirrorOptions flags as part\r
 161 /// of ovrMirrorTextureDesc's MirrorOptions field, and defaults to ovrMirrorOption_PostDistortion\r
 162 ///\r
 163 /// \see ovrMirrorOptions, ovr_CreateMirrorTextureWithOptionsDX\r
 164 ///\r
 165 OVR_PUBLIC_FUNCTION(ovrResult)\r
 166 ovr_CreateMirrorTextureDX(\r
 167     ovrSession session,\r
 168     IUnknown* d3dPtr,\r
 169     const ovrMirrorTextureDesc* desc,\r
 170     ovrMirrorTexture* out_MirrorTexture);\r
 171 \r
 172 /// Get a the underlying buffer as any compatible COM interface (similar to QueryInterface)\r
 173 ///\r
 174 /// \param[in]  session Specifies an ovrSession previously returned by ovr_Create.\r
 175 /// \param[in]  mirrorTexture Specifies an ovrMirrorTexture previously returned\r
 176 ///             by ovr_CreateMirrorTextureWithOptionsDX\r
 177 /// \param[in]  iid Specifies the interface ID of the interface pointer to query the buffer for.\r
 178 /// \param[out] out_Buffer Returns the COM interface pointer retrieved.\r
 179 ///\r
 180 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use\r
 181 ///         ovr_GetLastErrorInfo to get more information.\r
 182 ///\r
 183 /// <b>Example code</b>\r
 184 ///     \code{.cpp}\r
 185 ///         ID3D11Texture2D* d3d11Texture = nullptr;\r
 186 ///         ovr_GetMirrorTextureBufferDX(session, mirrorTexture, IID_PPV_ARGS(&d3d11Texture));\r
 187 ///         d3d11DeviceContext->CopyResource(d3d11TextureBackBuffer, d3d11Texture);\r
 188 ///         d3d11Texture->Release();\r
 189 ///         dxgiSwapChain->Present(0, 0);\r
 190 ///     \endcode\r
 191 ///\r
 192 OVR_PUBLIC_FUNCTION(ovrResult)\r
 193 ovr_GetMirrorTextureBufferDX(\r
 194     ovrSession session,\r
 195     ovrMirrorTexture mirrorTexture,\r
 196     IID iid,\r
 197     void** out_Buffer);\r
 198 \r
 199 #endif // !defined(OVR_EXPORTING_CAPI)\r
 200 \r
 201 #endif // _WIN32\r
 202 \r
 203 #endif // OVR_CAPI_D3D_h\r