Debian Codegraph @

examples/quick/scenegraph/metaltextureimport/doc/src/metaltextureimport.qdoc

raw
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 */