1 /********************************************************************************/ /**
\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
7 #ifndef OVR_CAPI_D3D_h
\r
8 #define OVR_CAPI_D3D_h
\r
10 #include "OVR_CAPI.h"
\r
11 #include "OVR_Version.h"
\r
16 #include <guiddef.h>
\r
18 #if !defined(OVR_EXPORTING_CAPI)
\r
20 //-----------------------------------------------------------------------------------
\r
21 // ***** Direct3D Specific
\r
23 /// Create Texture Swap Chain suitable for use with Direct3D 11 and 12.
\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
38 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use
\r
39 /// ovr_GetLastErrorInfo to get more information.
\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
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
63 OVR_PUBLIC_FUNCTION(ovrResult)
\r
64 ovr_CreateTextureSwapChainDX(
\r
67 const ovrTextureSwapChainDesc* desc,
\r
68 ovrTextureSwapChain* out_TextureSwapChain);
\r
70 /// Get a specific buffer within the chain as any compatible COM interface (similar to
\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
83 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use
\r
84 /// ovr_GetLastErrorInfo to get more information.
\r
86 /// <b>Example code</b>
\r
88 /// ovr_GetTextureSwapChainBufferDX(session, chain, 0, IID_ID3D11Texture2D, &d3d11Texture);
\r
89 /// ovr_GetTextureSwapChainBufferDX(session, chain, 1, IID_PPV_ARGS(&dxgiResource));
\r
92 OVR_PUBLIC_FUNCTION(ovrResult)
\r
93 ovr_GetTextureSwapChainBufferDX(
\r
95 ovrTextureSwapChain chain,
\r
100 /// Create Mirror Texture which is auto-refreshed to mirror Rift contents produced by this
\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
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
117 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use
\r
118 /// ovr_GetLastErrorInfo to get more information.
\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
133 /// <b>Example code</b>
\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
143 /// // Destroy the texture when done with it.
\r
144 /// ovr_DestroyMirrorTexture(session, mirrorTexture);
\r
145 /// mirrorTexture = nullptr;
\r
148 /// \see ovr_GetMirrorTextureBufferDX
\r
149 /// \see ovr_DestroyMirrorTexture
\r
151 OVR_PUBLIC_FUNCTION(ovrResult)
\r
152 ovr_CreateMirrorTextureWithOptionsDX(
\r
153 ovrSession session,
\r
155 const ovrMirrorTextureDesc* desc,
\r
156 ovrMirrorTexture* out_MirrorTexture);
\r
158 /// Deprecated. Use ovr_CreateMirrorTextureWithOptionsDX instead
\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
163 /// \see ovrMirrorOptions, ovr_CreateMirrorTextureWithOptionsDX
\r
165 OVR_PUBLIC_FUNCTION(ovrResult)
\r
166 ovr_CreateMirrorTextureDX(
\r
167 ovrSession session,
\r
169 const ovrMirrorTextureDesc* desc,
\r
170 ovrMirrorTexture* out_MirrorTexture);
\r
172 /// Get a the underlying buffer as any compatible COM interface (similar to QueryInterface)
\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
180 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use
\r
181 /// ovr_GetLastErrorInfo to get more information.
\r
183 /// <b>Example code</b>
\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
192 OVR_PUBLIC_FUNCTION(ovrResult)
\r
193 ovr_GetMirrorTextureBufferDX(
\r
194 ovrSession session,
\r
195 ovrMirrorTexture mirrorTexture,
\r
197 void** out_Buffer);
\r
199 #endif // !defined(OVR_EXPORTING_CAPI)
\r
203 #endif // OVR_CAPI_D3D_h
\r