| 1 |
/**************************************************************************** |
| 2 |
** |
| 3 |
** Copyright (C) 2019 The Qt Company Ltd. |
| 4 |
** Contact: https://www.qt.io/licensing/ |
| 5 |
** |
| 6 |
** This file is part of the documentation of the Qt Toolkit. |
| 7 |
** |
| 8 |
** $QT_BEGIN_LICENSE:FDL$ |
| 9 |
** Commercial License Usage |
| 10 |
** Licensees holding valid commercial Qt licenses may use this file in |
| 11 |
** accordance with the commercial license agreement provided with the |
| 12 |
** Software or, alternatively, in accordance with the terms contained in |
| 13 |
** a written agreement between you and The Qt Company. For licensing terms |
| 14 |
** and conditions see https://www.qt.io/terms-conditions. For further |
| 15 |
** information use the contact form at https://www.qt.io/contact-us. |
| 16 |
** |
| 17 |
** GNU Free Documentation License Usage |
| 18 |
** Alternatively, this file may be used under the terms of the GNU Free |
| 19 |
** Documentation License version 1.3 as published by the Free Software |
| 20 |
** Foundation and appearing in the file included in the packaging of |
| 21 |
** this file. Please review the following information to ensure |
| 22 |
** the GNU Free Documentation License version 1.3 requirements |
| 23 |
** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| 24 |
** $QT_END_LICENSE$ |
| 25 |
** |
| 26 |
****************************************************************************/ |
| 27 |
|
| 28 |
/*! |
| 29 |
\example scenegraph/metaltextureimport |
| 30 |
\title Scene Graph - Metal Texture Import |
| 31 |
\ingroup qtquickexamples |
| 32 |
\brief Shows how to use a texture created directly with Metal. |
| 33 |
|
| 34 |
\image metaltextureimport-example.jpg |
| 35 |
|
| 36 |
The Metal Texture Import example shows how an application can import and |
| 37 |
use a |
| 38 |
\l{https://developer.apple.com/documentation/metal/mtltexture}{MTLTexture} |
| 39 |
in the Qt Quick scene. This provides an alternative to the \l{Scene Graph - |
| 40 |
Metal Under QML}{underlay}, overlay, or \l{Scene Graph - Custom Rendering |
| 41 |
with QSGRenderNode}{render node} approaches when it comes to integrating |
| 42 |
native Metal rendering. In many cases going through a texture, and |
| 43 |
therefore "flattening" the 3D contents first, is the best option to |
| 44 |
integrate and mix custom 3D contents with the 2D UI elements provided by Qt |
| 45 |
Quick. |
| 46 |
|
| 47 |
\snippet scenegraph/metaltextureimport/main.qml 1 |
| 48 |
\snippet scenegraph/metaltextureimport/main.qml 2 |
| 49 |
|
| 50 |
The application exposes a custom QQuickItem subclass under ther name of |
| 51 |
CustomTextureItem. This is instantiated in QML. The value of the \c t |
| 52 |
property is animated as well. |
| 53 |
|
| 54 |
\snippet scenegraph/metaltextureimport/metaltextureimport.h 1 |
| 55 |
|
| 56 |
The implementation of our custom item involves overriding |
| 57 |
QQuickItem::updatePaintNode(), as well as functions and slots related to |
| 58 |
geometry changes and cleanup. |
| 59 |
|
| 60 |
\snippet scenegraph/metaltextureimport/metaltextureimport.mm 1 |
| 61 |
|
| 62 |
We also need a scenegraph node. Instead of deriving directly from QSGNode, |
| 63 |
we can use QSGSimpleTextureNode which gives us some of the functionality |
| 64 |
pre-implemented as a convenience. |
| 65 |
|
| 66 |
\snippet scenegraph/metaltextureimport/metaltextureimport.mm 2 |
| 67 |
|
| 68 |
The updatePaintNode() function of the item is called on the render thread |
| 69 |
(if there is one), with the main (GUI) thread blocked. Here we create a new |
| 70 |
node if there has not yet been one, and update it. Accessing Qt objects |
| 71 |
living on the main thread is safe here, so sync() will calculate and copy |
| 72 |
the values it needs from QQuickItem or QQuickWindow. |
| 73 |
|
| 74 |
\snippet scenegraph/metaltextureimport/metaltextureimport.mm 3 |
| 75 |
|
| 76 |
The node does not merely rely on the typical QQuickItem - QSGNode |
| 77 |
update sequence, it connects to QQuickWindow::beforeRendering() as |
| 78 |
well. That is where the contents of the Metal texture will be updated by |
| 79 |
encoding a full render pass, targeting the texture, on the Qt Quicks |
| 80 |
scenegraph's command buffer. beforeRendering() is the right place for this, |
| 81 |
because the signal is emitted before Qt Quick starts to encode its own |
| 82 |
rendering commands. Choosing QQuickWindow::beforeRenderPassRecording() |
| 83 |
instead would be an error in this exanple. |
| 84 |
|
| 85 |
\snippet scenegraph/metaltextureimport/metaltextureimport.mm 4 |
| 86 |
\snippet scenegraph/metaltextureimport/metaltextureimport.mm 5 |
| 87 |
|
| 88 |
After copying the values we need, sync() also performs some graphics |
| 89 |
resource initialization. The MTLDevice is queried from the scenegraph. Once |
| 90 |
a MTLTexture is available, a QSGTexture wrapping (not owning) it is created |
| 91 |
via QQuickWindow::createTextureFromNativeObject(). This function is a |
| 92 |
modern equivalent to QQuickWindow::createTextureFromId() that is not tied |
| 93 |
to OpenGL. Finally, the QSGTexture is associated with the underlying |
| 94 |
materials by calling the base class' setTexture() function. |
| 95 |
|
| 96 |
\snippet scenegraph/metaltextureimport/metaltextureimport.mm 6 |
| 97 |
|
| 98 |
render(), the slot connected to beforeRendering(), encodes the rendering |
| 99 |
commands using the buffers and pipeline state objects created in sync(). |
| 100 |
|
| 101 |
*/ |