From 913146ccd401216f71f037ea304b5e61b7a138cf Mon Sep 17 00:00:00 2001
From: Paul Olav Tvete <paul.tvete@qt.io>
Date: Fri, 29 Nov 2019 12:41:38 +0100
Subject: RHI: new native texture API

The new version takes/returns a value that can be unpacked and passed to
other functions without knowing which backend is in use.

The old API will be removed in a later change when dependent modules have
been updated

Task-number: QTBUG-78570
Change-Id: I18d928ceef3cb617c0c509ecccb345551a7990af
Reviewed-by: Laszlo Agocs <laszlo.agocs@qt.io>
---
 src/gui/rhi/qrhi.cpp | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)

(limited to 'src/gui/rhi/qrhi.cpp')

diff --git a/src/gui/rhi/qrhi.cpp b/src/gui/rhi/qrhi.cpp
index ece5190ff7..58f30deb41 100644
--- a/src/gui/rhi/qrhi.cpp
+++ b/src/gui/rhi/qrhi.cpp
@@ -2159,6 +2159,32 @@ QRhiResource::Type QRhiRenderBuffer::resourceType() const
     \value ASTC_12x12
  */
 
+/*!
+    \class QRhiTexture::NativeTexture
+    \brief Contains information about the underlying native resources of a texture.
+ */
+
+/*!
+    \variable QRhiTexture::NativeTexture::object
+    \brief a pointer to the native object handle.
+
+    With OpenGL, the native handle is a GLuint value, so \c object is then a
+    pointer to a GLuint. With Vulkan, the native handle is a VkImage, so \c
+    object is a pointer to a VkImage. With Direct3D 11 and Metal \c
+    object is a pointer to a ID3D11Texture2D or MTLTexture pointer, respectively.
+
+    \note Pay attention to the fact that \a object is always a pointer
+    to the native texture handle type, even if the native type itself is a
+    pointer.
+ */
+
+/*!
+    \variable QRhiTexture::NativeTexture::layout
+    \brief Specifies the current image layout for APIs like Vulkan.
+
+    For Vulkan, \c layout contains a \c VkImageLayout value.
+ */
+
 /*!
     \internal
  */
@@ -2196,11 +2222,24 @@ QRhiResource::Type QRhiTexture::resourceType() const
     \sa QRhiVulkanTextureNativeHandles, QRhiD3D11TextureNativeHandles,
     QRhiMetalTextureNativeHandles, QRhiGles2TextureNativeHandles
  */
+// TODO: remove this version once QtQuick has stopped using it
 const QRhiNativeHandles *QRhiTexture::nativeHandles()
 {
     return nullptr;
 }
 
+/*!
+    \return the underlying native resources for this texture. The returned value
+    will be empty if exposing the underlying native resources is not supported by
+    the backend.
+
+    \sa buildFrom()
+ */
+QRhiTexture::NativeTexture QRhiTexture::nativeTexture()
+{
+    return {};
+}
+
 /*!
     Similar to build() except that no new native textures are created. Instead,
     the texture from \a src is used.
@@ -2224,12 +2263,40 @@ const QRhiNativeHandles *QRhiTexture::nativeHandles()
     \sa QRhiVulkanTextureNativeHandles, QRhiD3D11TextureNativeHandles,
     QRhiMetalTextureNativeHandles, QRhiGles2TextureNativeHandles
  */
+// TODO: remove this version once QtQuick has stopped using it
 bool QRhiTexture::buildFrom(const QRhiNativeHandles *src)
 {
     Q_UNUSED(src);
     return false;
 }
 
+/*!
+    Similar to build() except that no new native textures are created. Instead,
+    the native texture resources specified by \a src is used.
+
+    This allows importing an existing native texture object (which must belong
+    to the same device or sharing context, depending on the graphics API) from
+    an external graphics engine.
+
+    \note format(), pixelSize(), sampleCount(), and flags() must still be set
+    correctly. Passing incorrect sizes and other values to QRhi::newTexture()
+    and then following it with a buildFrom() expecting that the native texture
+    object alone is sufficient to deduce such values is \b wrong and will lead
+    to problems.
+
+    \note QRhiTexture does not take ownership of the texture object. release()
+    does not free the object or any associated memory.
+
+    The opposite of this operation, exposing a QRhiTexture-created native
+    texture object to a foreign engine, is possible via nativeTexture().
+
+*/
+bool QRhiTexture::buildFrom(QRhiTexture::NativeTexture src)
+{
+    Q_UNUSED(src);
+    return false;
+}
+
 /*!
     \class QRhiSampler
     \internal
-- 
cgit v1.2.3