Include/OVR_CAPI_Vk.h

   1 /********************************************************************************/ /**\r
   2  \file      OVR_CAPI_Vk.h\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
   6 \r
   7 #ifndef OVR_CAPI_Vk_h\r
   8 #define OVR_CAPI_Vk_h\r
   9 \r
  10 #include "OVR_CAPI.h"\r
  11 #include "OVR_Version.h"\r
  12 \r
  13 \r
  14 #if !defined(OVR_EXPORTING_CAPI)\r
  15 \r
  16 //-----------------------------------------------------------------------------------\r
  17 // ***** Vulkan Specific\r
  18 \r
  19 /// Get a list of Vulkan vkInstance extensions required for VR.\r
  20 ///\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
  24 ///\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
  32 ///\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
  37 ///\r
  38 /// <b>Example code</b>\r
  39 ///     \code{.cpp}\r
  40 ///         char extensionNames[4096];\r
  41 ///         uint32_t extensionNamesSize = sizeof(extensionNames);\r
  42 ///         ovr_GetInstanceExtensionsVk(luid, extensionsnames, &extensionNamesSize);\r
  43 ///\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
  50 ///                     p[-1] = '\0';\r
  51 ///             }\r
  52 ///         }\r
  53 ///\r
  54 ///         VkInstanceCreateInfo info = { ... };\r
  55 ///         info.enabledExtensionCount = extensionCount;\r
  56 ///         info.ppEnabledExtensionNames = extensionNamePtrs;\r
  57 ///         [...]\r
  58 ///     \endcode\r
  59 ///\r
  60 OVR_PUBLIC_FUNCTION(ovrResult)\r
  61 ovr_GetInstanceExtensionsVk(\r
  62     ovrGraphicsLuid luid,\r
  63     char* extensionNames,\r
  64     uint32_t* inoutExtensionNamesSize);\r
  65 \r
  66 /// Get a list of Vulkan vkDevice extensions required for VR.\r
  67 ///\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
  71 ///\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
  79 ///\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
  84 ///\r
  85 OVR_PUBLIC_FUNCTION(ovrResult)\r
  86 ovr_GetDeviceExtensionsVk(\r
  87     ovrGraphicsLuid luid,\r
  88     char* extensionNames,\r
  89     uint32_t* inoutExtensionNamesSize);\r
  90 \r
  91 /// Find VkPhysicalDevice matching ovrGraphicsLuid\r
  92 ///\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
  97 ///\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
 100 ///\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
 106 ///\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
 113 \r
 114 /// Select VkQueue to block on till rendering is complete\r
 115 ///\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
 118 ///\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
 121 ///\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
 127 ///\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
 134 #endif\r
 135 \r
 136 /// Create Texture Swap Chain suitable for use with Vulkan\r
 137 ///\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
 146 ///\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
 149 ///\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
 166 ///\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
 172 ///\r
 173 OVR_PUBLIC_FUNCTION(ovrResult)\r
 174 ovr_CreateTextureSwapChainVk(\r
 175     ovrSession session,\r
 176     VkDevice device,\r
 177     const ovrTextureSwapChainDesc* desc,\r
 178     ovrTextureSwapChain* out_TextureSwapChain);\r
 179 \r
 180 /// Get a specific VkImage within the chain\r
 181 ///\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
 190 ///\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
 193 ///\r
 194 OVR_PUBLIC_FUNCTION(ovrResult)\r
 195 ovr_GetTextureSwapChainBufferVk(\r
 196     ovrSession session,\r
 197     ovrTextureSwapChain chain,\r
 198     int index,\r
 199     VkImage* out_Image);\r
 200 \r
 201 /// Create Mirror Texture which is auto-refreshed to mirror Rift contents produced by this\r
 202 /// application.\r
 203 ///\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
 206 ///\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
 215 ///\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
 218 ///\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
 231 ///\r
 232 /// <b>Example code</b>\r
 233 ///     \code{.cpp}\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
 241 ///         [...]\r
 242 ///         // Destroy the texture when done with it.\r
 243 ///         ovr_DestroyMirrorTexture(session, mirrorTexture);\r
 244 ///         mirrorTexture = nullptr;\r
 245 ///     \endcode\r
 246 ///\r
 247 /// \see ovr_GetMirrorTextureBufferVk\r
 248 /// \see ovr_DestroyMirrorTexture\r
 249 ///\r
 250 OVR_PUBLIC_FUNCTION(ovrResult)\r
 251 ovr_CreateMirrorTextureWithOptionsVk(\r
 252     ovrSession session,\r
 253     VkDevice device,\r
 254     const ovrMirrorTextureDesc* desc,\r
 255     ovrMirrorTexture* out_MirrorTexture);\r
 256 \r
 257 /// Get a the underlying mirror VkImage\r
 258 ///\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
 263 ///\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
 266 ///\r
 267 /// <b>Example code</b>\r
 268 ///     \code{.cpp}\r
 269 ///         VkImage mirrorImage = VK_NULL_HANDLE;\r
 270 ///         ovr_GetMirrorTextureBufferVk(session, mirrorTexture, &mirrorImage);\r
 271 ///         ...\r
 272 ///         vkCmdBlitImage(commandBuffer, mirrorImage, VK_IMAGE_LAYOUT_TRANSFER_SRC_OPTIMAL,\r
 273 ///         presentImage, VK_IMAGE_LAYOUT_TRANSFER_DST_OPTIMAL, 1, &region, VK_FILTER_LINEAR);\r
 274 ///         ...\r
 275 ///         vkQueuePresentKHR(queue, &presentInfo);\r
 276 ///     \endcode\r
 277 ///\r
 278 OVR_PUBLIC_FUNCTION(ovrResult)\r
 279 ovr_GetMirrorTextureBufferVk(\r
 280     ovrSession session,\r
 281     ovrMirrorTexture mirrorTexture,\r
 282     VkImage* out_Image);\r
 283 \r
 284 #endif // !defined(OVR_EXPORTING_CAPI)\r
 285 \r
 286 #endif // OVR_CAPI_Vk_h\r