diff options
Diffstat (limited to 'examples/quick/scenegraph/metaltextureimport/doc/src/metaltextureimport.qdoc')
-rw-r--r-- | examples/quick/scenegraph/metaltextureimport/doc/src/metaltextureimport.qdoc | 101 |
1 files changed, 101 insertions, 0 deletions
diff --git a/examples/quick/scenegraph/metaltextureimport/doc/src/metaltextureimport.qdoc b/examples/quick/scenegraph/metaltextureimport/doc/src/metaltextureimport.qdoc new file mode 100644 index 0000000000..2a584c26cc --- /dev/null +++ b/examples/quick/scenegraph/metaltextureimport/doc/src/metaltextureimport.qdoc @@ -0,0 +1,101 @@ +/**************************************************************************** +** +** Copyright (C) 2019 The Qt Company Ltd. +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** Commercial License Usage +** Licensees holding valid commercial Qt licenses may use this file in +** accordance with the commercial license agreement provided with the +** Software or, alternatively, in accordance with the terms contained in +** a written agreement between you and The Qt Company. For licensing terms +** and conditions see https://www.qt.io/terms-conditions. For further +** information use the contact form at https://www.qt.io/contact-us. +** +** GNU Free Documentation License Usage +** Alternatively, this file may be used under the terms of the GNU Free +** Documentation License version 1.3 as published by the Free Software +** Foundation and appearing in the file included in the packaging of +** this file. Please review the following information to ensure +** the GNU Free Documentation License version 1.3 requirements +** will be met: https://www.gnu.org/licenses/fdl-1.3.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \example scenegraph/metaltextureimport + \title Scene Graph - Metal Texture Import + \ingroup qtquickexamples + \brief Shows how to use a texture created directly with Metal + + \image metaltextureimport-example.jpg + + The Metal Texture Import example shows how an application can import and + use a + \l{https://developer.apple.com/documentation/metal/mtltexture}{MTLTexture} + in the Qt Quick scene. This provides an alternative to the \l{Scene Graph - + Metal Under QML}{underlay}, overlay, or \l{Scene Graph - Custom Rendering + with QSGRenderNode}{render node} approaches when it comes to integrating + native Metal rendering. In many cases going through a texture, and + therefore "flattening" the 3D contents first, is the best option to + integrate and mix custom 3D contents with the 2D UI elements provided by Qt + Quick. + + \snippet scenegraph/metaltextureimport/main.qml 1 + \snippet scenegraph/metaltextureimport/main.qml 2 + + The application exposes a custom QQuickItem subclass under ther name of + CustomTextureItem. This is instantiated in QML. The value of the \c t + property is animated as well. + + \snippet scenegraph/metaltextureimport/metaltextureimport.h 1 + + The implementation of our custom item involves overriding + QQuickItem::updatePaintNode(), as well as functions and slots related to + geometry changes and cleanup. + + \snippet scenegraph/metaltextureimport/metaltextureimport.mm 1 + + We also need a scenegraph node. Instead of deriving directly from QSGNode, + we can use QSGSimpleTextureNode which gives us some of the functionality + pre-implemented as a convenience. + + \snippet scenegraph/metaltextureimport/metaltextureimport.mm 2 + + The updatePaintNode() function of the item is called on the render thread + (if there is one), with the main (gui) thread blocked. Here we create a new + node if there has not yet been one, and update it. Accessing Qt objects + living on the main thread is safe here, so sync() will calculate and copy + the values it needs from QQuickItem or QQuickWindow. + + \snippet scenegraph/metaltextureimport/metaltextureimport.mm 3 + + The node does not merely rely on the typical QQuickItem - QSGNode + update sequence, it connects to QQuickWindow::beforeRendering() as + well. That is where the contents of the Metal texture will be updated by + encoding a full render pass, targeting the texture, on the Qt Quicks + scenegraph's command buffer. beforeRendering() is the right place for this, + because the signal is emitted before Qt Quick starts to encode its own + rendering commands. Choosing QQuickWindow::beforeRenderPassRecording() + instead would be an error in this exanple. + + \snippet scenegraph/metaltextureimport/metaltextureimport.mm 4 + \snippet scenegraph/metaltextureimport/metaltextureimport.mm 5 + + After copying the values we need, sync() also performs some graphics + resource initialization. The MTLDevice is queried from the scenegraph. Once + a MTLTexture is available, a QSGTexture wrapping (not owning) it is created + via QQuickWindow::createTextureFromNativeObject(). This function is a + modern equivalent to QQuickWindow::createTextureFromId() that is not tied + to OpenGL. Finally, the QSGTexture is associated with the underlying + materials by calling the base class' setTexture() function. + + \snippet scenegraph/metaltextureimport/metaltextureimport.mm 6 + + render(), the slot connected to beforeRendering(), encodes the rendering + commands using the buffers and pipeline state objects created in sync(). + + */ |