1 /********************************************************************************/ /**
\r
3 \brief Vulkan specific structures used by the CAPI interface.
\r
4 \copyright Copyright 2014-2017 Oculus VR, LLC All Rights reserved.
\r
5 ************************************************************************************/
\r
7 #ifndef OVR_CAPI_Vk_h
\r
8 #define OVR_CAPI_Vk_h
\r
10 #include "OVR_CAPI.h"
\r
11 #include "OVR_Version.h"
\r
14 #if !defined(OVR_EXPORTING_CAPI)
\r
16 //-----------------------------------------------------------------------------------
\r
17 // ***** Vulkan Specific
\r
19 /// Get a list of Vulkan vkInstance extensions required for VR.
\r
21 /// Returns a list of strings delimited by a single space identifying Vulkan extensions that must
\r
22 /// be enabled in order for the VR runtime to support Vulkan-based applications. The returned
\r
23 /// list reflects the current runtime version and the GPU the VR system is currently connected to.
\r
25 /// \param[in] luid Specifies the luid for the relevant GPU, which is returned from ovr_Create.
\r
26 /// \param[in] extensionNames is a character buffer which will receive a list of extension name
\r
27 /// strings, separated by a single space char between each extension.
\r
28 /// \param[in] inoutExtensionNamesSize indicates on input the capacity of extensionNames in chars.
\r
29 /// On output it returns the number of characters written to extensionNames,
\r
30 /// including the terminating 0 char. In the case of this function returning
\r
31 /// ovrError_InsufficientArraySize, the required inoutExtensionNamesSize is returned.
\r
33 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use
\r
34 /// ovr_GetLastErrorInfo to get more information. Returns ovrError_InsufficientArraySize in
\r
35 /// the case that inoutExtensionNameSize didn't have enough space, in which case
\r
36 /// inoutExtensionNameSize will return the required inoutExtensionNamesSize.
\r
38 /// <b>Example code</b>
\r
40 /// char extensionNames[4096];
\r
41 /// uint32_t extensionNamesSize = sizeof(extensionNames);
\r
42 /// ovr_GetInstanceExtensionsVk(luid, extensionsnames, &extensionNamesSize);
\r
44 /// uint32_t extensionCount = 0;
\r
45 /// const char* extensionNamePtrs[256];
\r
46 /// for(const char* p = extensionNames; *p; ++p) {
\r
47 /// if((p == extensionNames) || (p[-1] == ' ')) {
\r
48 /// extensionNamePtrs[extensionCount++] = p;
\r
49 /// if (p[-1] == ' ')
\r
54 /// VkInstanceCreateInfo info = { ... };
\r
55 /// info.enabledExtensionCount = extensionCount;
\r
56 /// info.ppEnabledExtensionNames = extensionNamePtrs;
\r
60 OVR_PUBLIC_FUNCTION(ovrResult)
\r
61 ovr_GetInstanceExtensionsVk(
\r
62 ovrGraphicsLuid luid,
\r
63 char* extensionNames,
\r
64 uint32_t* inoutExtensionNamesSize);
\r
66 /// Get a list of Vulkan vkDevice extensions required for VR.
\r
68 /// Returns a list of strings delimited by a single space identifying Vulkan extensions that must
\r
69 /// be enabled in order for the VR runtime to support Vulkan-based applications. The returned
\r
70 /// list reflects the current runtime version and the GPU the VR system is currently connected to.
\r
72 /// \param[in] luid Specifies the luid for the relevant GPU, which is returned from ovr_Create.
\r
73 /// \param[in] extensionNames is a character buffer which will receive a list of extension name
\r
74 /// strings, separated by a single space char between each extension.
\r
75 /// \param[in] inoutExtensionNamesSize indicates on input the capacity of extensionNames in chars.
\r
76 /// On output it returns the number of characters written to extensionNames,
\r
77 /// including the terminating 0 char. In the case of this function returning
\r
78 /// ovrError_InsufficientArraySize, the required inoutExtensionNamesSize is returned.
\r
80 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use
\r
81 /// ovr_GetLastErrorInfo to get more information. Returns ovrError_InsufficientArraySize in
\r
82 /// the case that inoutExtensionNameSize didn't have enough space, in which case
\r
83 /// inoutExtensionNameSize will return the required inoutExtensionNamesSize.
\r
85 OVR_PUBLIC_FUNCTION(ovrResult)
\r
86 ovr_GetDeviceExtensionsVk(
\r
87 ovrGraphicsLuid luid,
\r
88 char* extensionNames,
\r
89 uint32_t* inoutExtensionNamesSize);
\r
91 /// Find VkPhysicalDevice matching ovrGraphicsLuid
\r
93 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
94 /// \param[in] luid Specifies the luid returned from ovr_Create.
\r
95 /// \param[in] instance Specifies a VkInstance to search for matching luids in.
\r
96 /// \param[out] out_physicalDevice Returns the VkPhysicalDevice matching the instance and luid.
\r
98 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use
\r
99 /// ovr_GetLastErrorInfo to get more information.
\r
101 /// \note This function enumerates the current physical devices and returns the one matching the
\r
102 /// luid. It must be called at least once prior to any ovr_CreateTextureSwapChainVk or
\r
103 /// ovr_CreateMirrorTextureWithOptionsVk calls, and the instance must remain valid for the lifetime
\r
104 /// of the returned objects. It is assumed the VkDevice created by the application will be for the
\r
105 /// returned physical device.
\r
107 OVR_PUBLIC_FUNCTION(ovrResult)
\r
108 ovr_GetSessionPhysicalDeviceVk(
\r
109 ovrSession session,
\r
110 ovrGraphicsLuid luid,
\r
111 VkInstance instance,
\r
112 VkPhysicalDevice* out_physicalDevice);
\r
114 /// Select VkQueue to block on till rendering is complete
\r
116 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
117 /// \param[in] queue Specifies a VkQueue to add a VkFence operation to and wait on.
\r
119 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use
\r
120 /// ovr_GetLastErrorInfo to get more information.
\r
122 /// \note The queue may be changed at any time but only the value at the time ovr_SubmitFrame
\r
123 /// is called will be used. ovr_SetSynchronizationQueueVk must be called with a valid VkQueue
\r
124 /// created on the same VkDevice the texture sets were created on prior to the first call to
\r
125 /// ovr_SubmitFrame. An internally created VkFence object will be signalled by the completion
\r
126 /// of operations on queue and waited on to synchronize the VR compositor.
\r
128 OVR_PUBLIC_FUNCTION(ovrResult) ovr_SetSynchronizationQueueVk(ovrSession session, VkQueue queue);
\r
129 // Backwards compatibility for the original typoed version
\r
130 #define ovr_SetSynchonizationQueueVk ovr_SetSynchronizationQueueVk
\r
131 // Define OVR_PREVIEW_DEPRECATION to generate warnings for upcoming API deprecations
\r
132 #if defined(OVR_PREVIEW_DEPRECATION)
\r
133 #pragma deprecated("ovr_SetSynchonizationQueueVk")
\r
136 /// Create Texture Swap Chain suitable for use with Vulkan
\r
138 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
139 /// \param[in] device Specifies the application's VkDevice to create resources with.
\r
140 /// \param[in] desc Specifies requested texture properties. See notes for more info
\r
141 /// about texture format.
\r
142 /// \param[out] out_TextureSwapChain Returns the created ovrTextureSwapChain, which will be valid
\r
143 /// upon a successful return value, else it will be NULL.
\r
144 /// This texture chain must be eventually destroyed via ovr_DestroyTextureSwapChain
\r
145 /// before destroying the session with ovr_Destroy.
\r
147 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use
\r
148 /// ovr_GetLastErrorInfo to get more information.
\r
150 /// \note The texture format provided in \a desc should be thought of as the format the
\r
151 /// distortion-compositor will use for the ShaderResourceView when reading the contents
\r
152 /// of the texture. To that end, it is highly recommended that the application
\r
153 /// requests texture swapchain formats that are in sRGB-space
\r
154 /// (e.g. OVR_FORMAT_R8G8B8A8_UNORM_SRGB) as the compositor does sRGB-correct rendering.
\r
155 /// As such, the compositor relies on the GPU's hardware sampler to do the sRGB-to-linear
\r
156 /// conversion. If the application still prefers to render to a linear format (e.g.
\r
157 /// OVR_FORMAT_R8G8B8A8_UNORM) while handling the linear-to-gamma conversion via
\r
158 /// SPIRV code, then the application must still request the corresponding sRGB format and
\r
159 /// also use the \a ovrTextureMisc_DX_Typeless flag in the ovrTextureSwapChainDesc's
\r
160 /// Flag field. This will allow the application to create a RenderTargetView that is the
\r
161 /// desired linear format while the compositor continues to treat it as sRGB. Failure to
\r
162 /// do so will cause the compositor to apply unexpected gamma conversions leading to
\r
163 /// gamma-curve artifacts. The \a ovrTextureMisc_DX_Typeless flag for depth buffer formats
\r
164 /// (e.g. OVR_FORMAT_D32_FLOAT) is ignored as they are always
\r
165 /// converted to be typeless.
\r
167 /// \see ovr_GetTextureSwapChainLength
\r
168 /// \see ovr_GetTextureSwapChainCurrentIndex
\r
169 /// \see ovr_GetTextureSwapChainDesc
\r
170 /// \see ovr_GetTextureSwapChainBufferVk
\r
171 /// \see ovr_DestroyTextureSwapChain
\r
173 OVR_PUBLIC_FUNCTION(ovrResult)
\r
174 ovr_CreateTextureSwapChainVk(
\r
175 ovrSession session,
\r
177 const ovrTextureSwapChainDesc* desc,
\r
178 ovrTextureSwapChain* out_TextureSwapChain);
\r
180 /// Get a specific VkImage within the chain
\r
182 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
183 /// \param[in] chain Specifies an ovrTextureSwapChain previously returned by
\r
184 /// ovr_CreateTextureSwapChainVk
\r
185 /// \param[in] index Specifies the index within the chain to retrieve.
\r
186 /// Must be between 0 and length (see ovr_GetTextureSwapChainLength),
\r
187 /// or may pass -1 to get the buffer at the CurrentIndex location (saving a
\r
188 /// call to GetTextureSwapChainCurrentIndex).
\r
189 /// \param[out] out_Image Returns the VkImage retrieved.
\r
191 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use
\r
192 /// ovr_GetLastErrorInfo to get more information.
\r
194 OVR_PUBLIC_FUNCTION(ovrResult)
\r
195 ovr_GetTextureSwapChainBufferVk(
\r
196 ovrSession session,
\r
197 ovrTextureSwapChain chain,
\r
199 VkImage* out_Image);
\r
201 /// Create Mirror Texture which is auto-refreshed to mirror Rift contents produced by this
\r
204 /// A second call to ovr_CreateMirrorTextureWithOptionsVk for a given ovrSession before destroying
\r
205 /// the first one is not supported and will result in an error return.
\r
207 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
208 /// \param[in] device Specifies the VkDevice to create resources with.
\r
209 /// \param[in] desc Specifies requested texture properties. See notes for more info
\r
210 /// about texture format.
\r
211 /// \param[out] out_MirrorTexture Returns the created ovrMirrorTexture, which will be
\r
212 /// valid upon a successful return value, else it will be NULL.
\r
213 /// This texture must be eventually destroyed via ovr_DestroyMirrorTexture before
\r
214 /// destroying the session with ovr_Destroy.
\r
216 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use
\r
217 /// ovr_GetLastErrorInfo to get more information.
\r
219 /// \note The texture format provided in \a desc should be thought of as the format the
\r
220 /// compositor will use for the VkImageView when writing into mirror texture. To that end,
\r
221 /// it is highly recommended that the application requests a mirror texture format that is
\r
222 /// in sRGB-space (e.g. OVR_FORMAT_R8G8B8A8_UNORM_SRGB) as the compositor does sRGB-correct
\r
223 /// rendering. If however the application wants to still read the mirror texture as a
\r
224 /// linear format (e.g. OVR_FORMAT_R8G8B8A8_UNORM) and handle the sRGB-to-linear conversion
\r
225 /// in SPIRV code, then it is recommended the application still requests an sRGB format and
\r
226 /// also use the \a ovrTextureMisc_DX_Typeless flag in the ovrMirrorTextureDesc's
\r
227 /// Flags field. This will allow the application to bind a ShaderResourceView that is a
\r
228 /// linear format while the compositor continues to treat is as sRGB. Failure to do so will
\r
229 /// cause the compositor to apply unexpected gamma conversions leading to
\r
230 /// gamma-curve artifacts.
\r
232 /// <b>Example code</b>
\r
234 /// ovrMirrorTexture mirrorTexture = nullptr;
\r
235 /// ovrMirrorTextureDesc mirrorDesc = {};
\r
236 /// mirrorDesc.Format = OVR_FORMAT_R8G8B8A8_UNORM_SRGB;
\r
237 /// mirrorDesc.Width = mirrorWindowWidth;
\r
238 /// mirrorDesc.Height = mirrorWindowHeight;
\r
239 /// ovrResult result = ovr_CreateMirrorTextureWithOptionsVk(session, vkDevice, &mirrorDesc,
\r
240 /// &mirrorTexture);
\r
242 /// // Destroy the texture when done with it.
\r
243 /// ovr_DestroyMirrorTexture(session, mirrorTexture);
\r
244 /// mirrorTexture = nullptr;
\r
247 /// \see ovr_GetMirrorTextureBufferVk
\r
248 /// \see ovr_DestroyMirrorTexture
\r
250 OVR_PUBLIC_FUNCTION(ovrResult)
\r
251 ovr_CreateMirrorTextureWithOptionsVk(
\r
252 ovrSession session,
\r
254 const ovrMirrorTextureDesc* desc,
\r
255 ovrMirrorTexture* out_MirrorTexture);
\r
257 /// Get a the underlying mirror VkImage
\r
259 /// \param[in] session Specifies an ovrSession previously returned by ovr_Create.
\r
260 /// \param[in] mirrorTexture Specifies an ovrMirrorTexture previously returned by
\r
261 /// ovr_CreateMirrorTextureWithOptionsVk
\r
262 /// \param[out] out_Image Returns the VkImage pointer retrieved.
\r
264 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use
\r
265 /// ovr_GetLastErrorInfo to get more information.
\r
267 /// <b>Example code</b>
\r
269 /// VkImage mirrorImage = VK_NULL_HANDLE;
\r
270 /// ovr_GetMirrorTextureBufferVk(session, mirrorTexture, &mirrorImage);
\r
272 /// vkCmdBlitImage(commandBuffer, mirrorImage, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL,
\r
273 /// presentImage, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 1, ®ion, VK_FILTER_LINEAR);
\r
275 /// vkQueuePresentKHR(queue, &presentInfo);
\r
278 OVR_PUBLIC_FUNCTION(ovrResult)
\r
279 ovr_GetMirrorTextureBufferVk(
\r
280 ovrSession session,
\r
281 ovrMirrorTexture mirrorTexture,
\r
282 VkImage* out_Image);
\r
284 #endif // !defined(OVR_EXPORTING_CAPI)
\r
286 #endif // OVR_CAPI_Vk_h
\r