Include/OVR_CAPI_GL.h

   1 /********************************************************************************/ /**\r
   2  \file      OVR_CAPI_GL.h\r
   3  \brief     OpenGL-specific structures used by the CAPI interface.\r
   4  \copyright Copyright 2015 Oculus VR, LLC. All Rights reserved.\r
   5  ************************************************************************************/\r
   6 \r
   7 #ifndef OVR_CAPI_GL_h\r
   8 #define OVR_CAPI_GL_h\r
   9 \r
  10 #include "OVR_CAPI.h"\r
  11 \r
  12 #if !defined(OVR_EXPORTING_CAPI)\r
  13 \r
  14 /// Creates a TextureSwapChain suitable for use with OpenGL.\r
  15 ///\r
  16 /// \param[in]  session Specifies an ovrSession previously returned by ovr_Create.\r
  17 /// \param[in]  desc Specifies the requested texture properties.\r
  18 ///             See notes for more info about texture format.\r
  19 /// \param[out] out_TextureSwapChain Returns the created ovrTextureSwapChain,\r
  20 ///             which will be valid upon a successful return value, else it will be NULL.\r
  21 ///             This texture swap chain must be eventually destroyed via\r
  22 //              ovr_DestroyTextureSwapChain before destroying the session with ovr_Destroy.\r
  23 ///\r
  24 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use\r
  25 ///         ovr_GetLastErrorInfo to get more information.\r
  26 ///\r
  27 /// \note The \a format provided should be thought of as the format the distortion compositor will\r
  28 ///       use when reading the contents of the texture. To that end, it is highly recommended\r
  29 ///       that the application requests texture swap chain formats that are in sRGB-space\r
  30 ///       (e.g. OVR_FORMAT_R8G8B8A8_UNORM_SRGB) as the distortion compositor does sRGB-correct\r
  31 ///       rendering. Furthermore, the app should then make sure "glEnable(GL_FRAMEBUFFER_SRGB);"\r
  32 ///       is called before rendering into these textures. Even though it is not recommended,\r
  33 ///       if the application would like to treat the texture as a linear format and do\r
  34 ///       linear-to-gamma conversion in GLSL, then the application can avoid\r
  35 ///       calling "glEnable(GL_FRAMEBUFFER_SRGB);", but should still pass in an sRGB variant for\r
  36 ///       the \a format. Failure to do so will cause the distortion compositor to apply incorrect\r
  37 ///       gamma conversions leading to gamma-curve artifacts.\r
  38 ///\r
  39 /// \see ovr_GetTextureSwapChainLength\r
  40 /// \see ovr_GetTextureSwapChainCurrentIndex\r
  41 /// \see ovr_GetTextureSwapChainDesc\r
  42 /// \see ovr_GetTextureSwapChainBufferGL\r
  43 /// \see ovr_DestroyTextureSwapChain\r
  44 ///\r
  45 OVR_PUBLIC_FUNCTION(ovrResult)\r
  46 ovr_CreateTextureSwapChainGL(\r
  47     ovrSession session,\r
  48     const ovrTextureSwapChainDesc* desc,\r
  49     ovrTextureSwapChain* out_TextureSwapChain);\r
  50 \r
  51 /// Get a specific buffer within the chain as a GL texture name\r
  52 ///\r
  53 /// \param[in]  session Specifies an ovrSession previously returned by ovr_Create.\r
  54 /// \param[in]  chain Specifies an ovrTextureSwapChain previously returned\r
  55 ///             by ovr_CreateTextureSwapChainGL\r
  56 /// \param[in]  index Specifies the index within the chain to retrieve.\r
  57 ///             Must be between 0 and length (see ovr_GetTextureSwapChainLength)\r
  58 ///             or may pass -1 to get the buffer at the CurrentIndex location.\r
  59 ///             (Saving a call to GetTextureSwapChainCurrentIndex)\r
  60 /// \param[out] out_TexId Returns the GL texture object name associated with\r
  61 ///             the specific index requested\r
  62 ///\r
  63 /// \return Returns an ovrResult indicating success or failure.\r
  64 ///         In the case of failure, use ovr_GetLastErrorInfo to get more information.\r
  65 ///\r
  66 OVR_PUBLIC_FUNCTION(ovrResult)\r
  67 ovr_GetTextureSwapChainBufferGL(\r
  68     ovrSession session,\r
  69     ovrTextureSwapChain chain,\r
  70     int index,\r
  71     unsigned int* out_TexId);\r
  72 \r
  73 /// Creates a Mirror Texture which is auto-refreshed to mirror Rift contents produced by this\r
  74 /// application.\r
  75 ///\r
  76 /// A second call to ovr_CreateMirrorTextureWithOptionsGL for a given ovrSession before destroying\r
  77 /// the first one is not supported and will result in an error return.\r
  78 ///\r
  79 /// \param[in]  session Specifies an ovrSession previously returned by ovr_Create.\r
  80 /// \param[in]  desc Specifies the requested mirror texture description.\r
  81 /// \param[out] out_MirrorTexture Specifies the created ovrMirrorTexture, which will be\r
  82 ///             valid upon a successful return value, else it will be NULL.\r
  83 ///             This texture must be eventually destroyed via ovr_DestroyMirrorTexture before\r
  84 ///             destroying the session with ovr_Destroy.\r
  85 ///\r
  86 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use\r
  87 ///         ovr_GetLastErrorInfo to get more information.\r
  88 ///\r
  89 /// \note The \a format provided should be thought of as the format the distortion compositor will\r
  90 ///       use when writing into the mirror texture. It is highly recommended that mirror textures\r
  91 //        are requested as sRGB formats because the distortion compositor does sRGB-correct\r
  92 ///       rendering. If the application requests a non-sRGB format (e.g. R8G8B8A8_UNORM) as the\r
  93 ///       mirror texture, then the application might have to apply a manual linear-to-gamma\r
  94 ///       conversion when reading from the mirror texture. Failure to do so can result in\r
  95 //        incorrect gamma conversions leading to gamma-curve artifacts and color banding.\r
  96 ///\r
  97 /// \see ovr_GetMirrorTextureBufferGL\r
  98 /// \see ovr_DestroyMirrorTexture\r
  99 ///\r
 100 OVR_PUBLIC_FUNCTION(ovrResult)\r
 101 ovr_CreateMirrorTextureWithOptionsGL(\r
 102     ovrSession session,\r
 103     const ovrMirrorTextureDesc* desc,\r
 104     ovrMirrorTexture* out_MirrorTexture);\r
 105 \r
 106 /// Deprecated. Use ovr_CreateMirrorTextureWithOptionsGL instead\r
 107 ///\r
 108 /// Same as ovr_CreateMirrorTextureWithOptionsGL except doesn't use ovrMirrorOptions flags as part\r
 109 /// of ovrMirrorTextureDesc's MirrorOptions field, and defaults to ovrMirrorOption_PostDistortion\r
 110 ///\r
 111 /// \see ovrMirrorOptions, ovr_CreateMirrorTextureWithOptionsGL\r
 112 ///\r
 113 OVR_PUBLIC_FUNCTION(ovrResult)\r
 114 ovr_CreateMirrorTextureGL(\r
 115     ovrSession session,\r
 116     const ovrMirrorTextureDesc* desc,\r
 117     ovrMirrorTexture* out_MirrorTexture);\r
 118 \r
 119 /// Get a the underlying buffer as a GL texture name\r
 120 ///\r
 121 /// \param[in]  session Specifies an ovrSession previously returned by ovr_Create.\r
 122 /// \param[in]  mirrorTexture Specifies an ovrMirrorTexture previously returned\r
 123 //              by ovr_CreateMirrorTextureWithOptionsGL\r
 124 /// \param[out] out_TexId Specifies the GL texture object name associated with the mirror texture\r
 125 ///\r
 126 /// \return Returns an ovrResult indicating success or failure. In the case of failure, use\r
 127 ///         ovr_GetLastErrorInfo to get more information.\r
 128 ///\r
 129 OVR_PUBLIC_FUNCTION(ovrResult)\r
 130 ovr_GetMirrorTextureBufferGL(\r
 131     ovrSession session,\r
 132     ovrMirrorTexture mirrorTexture,\r
 133     unsigned int* out_TexId);\r
 134 \r
 135 #endif // !defined(OVR_EXPORTING_CAPI)\r
 136 \r
 137 #endif // OVR_CAPI_GL_h\r