diff options
author | Paul Wicking <paul.wicking@qt.io> | 2018-04-23 14:09:21 +0200 |
---|---|---|
committer | Paul Wicking <paul.wicking@qt.io> | 2018-04-27 08:33:39 +0000 |
commit | 3fc080b6bdacc440efae453413dd8053bbecacf5 (patch) | |
tree | 3c634ef9e50784f704353b6fcf692f546706aa50 | |
parent | 661f41e85c21b470a80c77aac3738a1ae24580a5 (diff) |
Doc: Add basic documentation for Scene3D QML module
Adds Scene3D as QML module.
Provides preliminary documentation for Scene3D QML type.
Task-number: QTBUG-61651
Task-number: QTBUG-54816
Change-Id: I2811bb2165ca0adde574ddde70fa7185b3c03083
Reviewed-by: Laszlo Agocs <laszlo.agocs@qt.io>
Reviewed-by: Topi Reiniƶ <topi.reinio@qt.io>
(cherry picked from commit 988928b9d37dfae08b5a98cd139eaaa14e72c02c)
-rw-r--r-- | examples/qt3d/scene3d/doc/src/scene3d.qdoc | 2 | ||||
-rw-r--r-- | src/doc/qt3d.qdocconf | 7 | ||||
-rw-r--r-- | src/doc/src/qt3d-module.qdoc | 5 | ||||
-rw-r--r-- | src/doc/src/qt3dscene3d-module.qdoc | 54 | ||||
-rw-r--r-- | src/quick3d/imports/scene3d/scene3ditem.cpp | 62 | ||||
-rw-r--r-- | src/quick3d/imports/scene3d/scene3drenderer.cpp | 8 | ||||
-rw-r--r-- | src/quick3d/imports/scene3d/scene3dsgmaterial.cpp | 10 |
7 files changed, 132 insertions, 16 deletions
diff --git a/examples/qt3d/scene3d/doc/src/scene3d.qdoc b/examples/qt3d/scene3d/doc/src/scene3d.qdoc index fd324e6a4..c6deb6546 100644 --- a/examples/qt3d/scene3d/doc/src/scene3d.qdoc +++ b/examples/qt3d/scene3d/doc/src/scene3d.qdoc @@ -33,7 +33,7 @@ \image scene3d.png - \e {Scene3D} demonstrates visualizing a 3D scene from a Qt Quick + This example demonstrates visualizing a 3D scene from a Qt Quick application. The 3D scene contains a single active camera and a single active light source. Visualized data is assumed to be at a fixed location. diff --git a/src/doc/qt3d.qdocconf b/src/doc/qt3d.qdocconf index 7da047ced..f006af29b 100644 --- a/src/doc/qt3d.qdocconf +++ b/src/doc/qt3d.qdocconf @@ -49,7 +49,8 @@ headerdirs += . \ ../input \ ../extras \ ../animation \ - ../quick3d/quick3dscene2d + ../quick3d/quick3dscene2d \ + ../quick3d/imports/scene3d # Exclude private header files from the documentation build excludefiles += "*_p.h" @@ -63,7 +64,9 @@ sourcedirs += . \ ../input \ ../extras \ ../animation \ - ../quick3d/quick3dscene2d + ../quick3d/quick3dscene2d \ + ../quick3d/imports/scene3d + exampledirs += ../../examples/qt3d \ snippets diff --git a/src/doc/src/qt3d-module.qdoc b/src/doc/src/qt3d-module.qdoc index 86a17342e..839245534 100644 --- a/src/doc/src/qt3d-module.qdoc +++ b/src/doc/src/qt3d-module.qdoc @@ -118,6 +118,8 @@ import Qt3D.Logic 2.0 import Qt3D.Extras 2.0 import Qt3D.Animation 2.9 + import Qt3D.Scene2D 2.9 + import Qt3D.Scene3D 2.9 \endcode \section1 QML Types @@ -146,4 +148,7 @@ \section2 Qt 3D Scene2D Module \generatelist {qmltypesbymodule Qt3D.Scene2D} \noautolist + + \section2 Qt 3D Scene3D Module + \generatelist {qmltypesbymodule Qt3D.Scene3D} */ diff --git a/src/doc/src/qt3dscene3d-module.qdoc b/src/doc/src/qt3dscene3d-module.qdoc new file mode 100644 index 000000000..08cf2d371 --- /dev/null +++ b/src/doc/src/qt3dscene3d-module.qdoc @@ -0,0 +1,54 @@ +/**************************************************************************** +** +** Copyright (C) 2018 The Qt Company Ltd and/or its subsidiary(-ies). +** Contact: https://www.qt.io/licensing/ +** +** This file is part of the Qt3D module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL$ +** 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 Lesser General Public License Usage +** Alternatively, this file may be used under the terms of the GNU Lesser +** General Public License version 3 as published by the Free Software +** Foundation and appearing in the file LICENSE.LGPL3 included in the +** packaging of this file. Please review the following information to +** ensure the GNU Lesser General Public License version 3 requirements +** will be met: https://www.gnu.org/licenses/lgpl-3.0.html. +** +** GNU General Public License Usage +** Alternatively, this file may be used under the terms of the GNU +** General Public License version 2.0 or (at your option) the GNU General +** Public license version 3 or any later version approved by the KDE Free +** Qt Foundation. The licenses are as published by the Free Software +** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3 +** included in the packaging of this file. Please review the following +** information to ensure the GNU General Public License requirements will +** be met: https://www.gnu.org/licenses/gpl-2.0.html and +** https://www.gnu.org/licenses/gpl-3.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \qmlmodule Qt3D.Scene3D 2.0 + \preliminary + \title Qt 3D Scene3D QML Types + \ingroup qmlmodules + \ingroup qt3d-qmlmodules-preliminary + + \brief Provides Qt 3D QML types for the Scene3D module. + + To import and use the module's QML types, use the following statement: + + \badcode + import Qt3D.Scene3D 2.0 + \endcode +*/ diff --git a/src/quick3d/imports/scene3d/scene3ditem.cpp b/src/quick3d/imports/scene3d/scene3ditem.cpp index ab832d463..6d91022e9 100644 --- a/src/quick3d/imports/scene3d/scene3ditem.cpp +++ b/src/quick3d/imports/scene3d/scene3ditem.cpp @@ -64,17 +64,33 @@ QT_BEGIN_NAMESPACE namespace Qt3DRender { /*! - \class Qt3DCore::Scene3DItem + \class Qt3DRender::Scene3DItem \internal - \brief The Qt3DCore::Scene3DItem class is a QQuickItem subclass used to integrate + \brief The Scene3DItem class is a QQuickItem subclass used to integrate a Qt3D scene into a QtQuick 2 scene. - The Qt3DCore::Scene3DItem class renders a Qt3D scene, provided by a Qt3DCore::QEntity - into a multisampled Framebuffer object that is later blitted into a non - multisampled Framebuffer object to be then renderer through the use of a + The Scene3DItem class renders a Qt3D scene, provided by a Qt3DCore::QEntity + into a multisampled Framebuffer object that is later blitted into a + non-multisampled Framebuffer object to be then rendered through the use of a Qt3DCore::Scene3DSGNode with premultiplied alpha. */ + +/*! + \qmltype Scene3D + \inherits Item + \inqmlmodule Qt3D.Scene3D + + \preliminary + + \brief The Scene3D type is used to integrate a Qt3D scene into a QtQuick 2 + scene. + + The Scene3D type renders a Qt3D scene, provided by an \l Entity, into a + multisampled Framebuffer object. This object is later blitted into a + non-multisampled Framebuffer object, which is then rendered with + premultiplied alpha. + */ Scene3DItem::Scene3DItem(QQuickItem *parent) : QQuickItem(parent) , m_entity(nullptr) @@ -97,11 +113,23 @@ Scene3DItem::~Scene3DItem() // Scene3DSGNode still exist and will perform their cleanup on their own. } +/*! + \qmlproperty list<string> Scene3D::aspects + + \brief \TODO + */ QStringList Scene3DItem::aspects() const { return m_aspects; } +/*! + \qmlproperty Entity Scene3D::entity + + \default + + \brief \TODO + */ Qt3DCore::QEntity *Scene3DItem::entity() const { return m_entity; @@ -161,6 +189,16 @@ void Scene3DItem::setHoverEnabled(bool enabled) } } +/*! + \qmlproperty enumeration Scene3D::cameraAspectRatioMode + + \value Scene3D.AutomaticAspectRatio + Automatic aspect ratio. + + \value Scene3D.UserAspectRatio + User defined aspect ratio. + \brief \TODO + */ Scene3DItem::CameraAspectRatioMode Scene3DItem::cameraAspectRatioMode() const { return m_cameraAspectRatioMode; @@ -222,7 +260,11 @@ void Scene3DItem::setWindowSurface(QObject *rootObject) } } } +/*! + \qmlmethod void Scene3D::setItemAreaAndDevicePixelRatio(size area, real devicePixelRatio) + \brief \TODO + */ void Scene3DItem::setItemAreaAndDevicePixelRatio(QSize area, qreal devicePixelRatio) { Qt3DRender::QRenderSurfaceSelector *surfaceSelector = Qt3DRender::QRenderSurfaceSelectorPrivate::find(m_entity); @@ -232,6 +274,11 @@ void Scene3DItem::setItemAreaAndDevicePixelRatio(QSize area, qreal devicePixelRa } } +/*! + \qmlproperty bool Scene3D::hoverEnabled + + \c true if hover events are accepted. + */ bool Scene3DItem::isHoverEnabled() const { return acceptHoverEvents(); @@ -262,6 +309,11 @@ void Scene3DItem::updateCameraAspectRatio() } /*! + \qmlproperty bool Scene3D::multisample + + \c true if a multi-sample render buffer is in use. + */ +/*! \return \c true if a multisample renderbuffer is in use. */ bool Scene3DItem::multisample() const diff --git a/src/quick3d/imports/scene3d/scene3drenderer.cpp b/src/quick3d/imports/scene3d/scene3drenderer.cpp index 4822c7bc4..b3cac0dcd 100644 --- a/src/quick3d/imports/scene3d/scene3drenderer.cpp +++ b/src/quick3d/imports/scene3d/scene3drenderer.cpp @@ -92,17 +92,18 @@ private: }; /*! - \class Qt3DCore::Scene3DRenderer + \class Qt3DRender::Scene3DRenderer \internal - \brief The Qt3DCore::Scene3DRenderer class takes care of rendering a Qt3D scene + \brief The Scene3DRenderer class takes care of rendering a Qt3D scene within a Framebuffer object to be used by the QtQuick 2 renderer. - The Qt3DCore::Scene3DRenderer class renders a Qt3D scene as provided by a Qt3DCore::Scene3DItem. + The Scene3DRenderer class renders a Qt3D scene as provided by a Scene3DItem. It owns the aspectEngine even though it doesn't instantiate it. The shutdown procedure is a two steps process that goes as follow: + \list \li The window is closed \li This triggers the windowsChanged signal which the Scene3DRenderer @@ -112,6 +113,7 @@ private: \li The destroyed signal of the window is also connected to the Scene3DRenderer. When triggered in the context of the main thread, the cleanup slot is called. + \endlist There is an alternate shutdown procedure in case the QQuickItem is destroyed with an active window which can happen in the case where the diff --git a/src/quick3d/imports/scene3d/scene3dsgmaterial.cpp b/src/quick3d/imports/scene3d/scene3dsgmaterial.cpp index a47d00268..1b8b08a4e 100644 --- a/src/quick3d/imports/scene3d/scene3dsgmaterial.cpp +++ b/src/quick3d/imports/scene3d/scene3dsgmaterial.cpp @@ -44,14 +44,14 @@ QT_BEGIN_NAMESPACE namespace Qt3DRender { /*! - \class Qt3DCore::Scene3DSGMaterial + \class Qt3DRender::Scene3DSGMaterial \internal - \inherit QSGMaterial + \inherits QSGMaterial - \brief The Qt3DRender::Scene3DSGMaterial class is a custom QSGMaterial subclass used to - render a Qt3DRender::Scene3DSGNode + \brief The Scene3DSGMaterial class is a custom QSGMaterial subclass used to + render a Scene3DSGNode - The Qt3DRender::Scene3DSGMaterial class renders a texture using premultiplied + The Scene3DSGMaterial class renders a texture using premultiplied alpha unlike the QSGSimpleTextureMaterial. This is needed to properly integrate alpha blending from a Qt3D scene |