Bring View3D and Studio3DProfiler back as public

This reverts commit 0752ab7e7b7c3d2e5daa6023c4ea93c84b8e45ec.

Change-Id: Ie2f71e19a8a05fd1d2554934a9dba235dca9933c
Reviewed-by: Christian Stromme <christian.stromme@qt.io>

16 files changed, 85 insertions, 12 deletions

diff --git a/examples/3dstudioruntime2/3dstudioruntime2.pro b/examples/3dstudioruntime2/3dstudioruntime2.pro
index 1ad83f1..37e384d 100644
--- a/examples/3dstudioruntime2/3dstudioruntime2.pro
+++ b/examples/3dstudioruntime2/3dstudioruntime2.pro
@@ -6,7 +6,8 @@ SUBDIRS += \
 
 qtHaveModule(quick) {
     SUBDIRS += simpleqml \
-               qmldatainput
+               qmldatainput \
+               layersinquick
 }
 
 qtHaveModule(widgets) {
diff --git a/tests/manual/layersinquick/doc/images/layersinquick.png b/examples/3dstudioruntime2/layersinquick/doc/images/layersinquick.png
index d486b90..d486b90 100644
--- a/tests/manual/layersinquick/doc/images/layersinquick.png
+++ b/examples/3dstudioruntime2/layersinquick/doc/images/layersinquick.png
diff --git a/tests/manual/layersinquick/doc/src/layersinquick.qdoc b/examples/3dstudioruntime2/layersinquick/doc/src/layersinquick.qdoc
index 46ed0f7..46ed0f7 100644
--- a/tests/manual/layersinquick/doc/src/layersinquick.qdoc
+++ b/examples/3dstudioruntime2/layersinquick/doc/src/layersinquick.qdoc
diff --git a/tests/manual/layersinquick/layers.uip b/examples/3dstudioruntime2/layersinquick/layers.uip
index 171f226..171f226 100644
--- a/tests/manual/layersinquick/layers.uip
+++ b/examples/3dstudioruntime2/layersinquick/layers.uip
diff --git a/tests/manual/layersinquick/layers_ssaa_msaa.uip b/examples/3dstudioruntime2/layersinquick/layers_ssaa_msaa.uip
index 9396fa8..9396fa8 100644
--- a/tests/manual/layersinquick/layers_ssaa_msaa.uip
+++ b/examples/3dstudioruntime2/layersinquick/layers_ssaa_msaa.uip
diff --git a/tests/manual/layersinquick/layersinquick.pro b/examples/3dstudioruntime2/layersinquick/layersinquick.pro
index 6a7ee56..f26e1c4 100644
--- a/tests/manual/layersinquick/layersinquick.pro
+++ b/examples/3dstudioruntime2/layersinquick/layersinquick.pro
@@ -1,3 +1,5 @@
+TEMPLATE = app
+
 QT += quick 3dstudioruntime2
 
 SOURCES += \
@@ -7,3 +9,6 @@ RESOURCES += layersinquick.qrc
 
 OTHER_FILES += \
     main.qml
+
+target.path = $$[QT_INSTALL_EXAMPLES]/3dstudioruntime2/$$TARGET
+INSTALLS += target
diff --git a/tests/manual/layersinquick/layersinquick.qrc b/examples/3dstudioruntime2/layersinquick/layersinquick.qrc
index e487405..e487405 100644
--- a/tests/manual/layersinquick/layersinquick.qrc
+++ b/examples/3dstudioruntime2/layersinquick/layersinquick.qrc
diff --git a/tests/manual/layersinquick/main.cpp b/examples/3dstudioruntime2/layersinquick/main.cpp
index 728e75d..728e75d 100644
--- a/tests/manual/layersinquick/main.cpp
+++ b/examples/3dstudioruntime2/layersinquick/main.cpp
diff --git a/tests/manual/layersinquick/main.qml b/examples/3dstudioruntime2/layersinquick/main.qml
index 9fd3da9..f7e3d39 100644
--- a/tests/manual/layersinquick/main.qml
+++ b/examples/3dstudioruntime2/layersinquick/main.qml
@@ -49,7 +49,7 @@
 ****************************************************************************/
 
 import QtQuick 2.0
-import QtStudio3D 2.1
+import QtStudio3D 2.2
 import QtQuick.Controls 2.2
 
 Rectangle {
diff --git a/src/imports/studio3d/plugin.cpp b/src/imports/studio3d/plugin.cpp
index 6ecba95..e86fc2b 100644
--- a/src/imports/studio3d/plugin.cpp
+++ b/src/imports/studio3d/plugin.cpp
@@ -82,9 +82,9 @@ public:
         qmlRegisterType<Q3DSViewerSettings>(uri, 2, 0, "ViewerSettings");
         qmlRegisterType<Q3DSInlineQmlSubPresentation>(uri, 2, 0, "QmlStream");
 
-        qmlRegisterType<Q3DSStudio3DView>(uri, 2, 1, "View3D");
+        qmlRegisterType<Q3DSStudio3DView>(uri, 2, 2, "View3D");
 #if QT_CONFIG(q3ds_profileui)
-        qmlRegisterType<Q3DSImGuiItem>(uri, 2, 1, "Studio3DProfiler");
+        qmlRegisterType<Q3DSImGuiItem>(uri, 2, 2, "Studio3DProfiler");
 #endif
 
         // API NG
diff --git a/src/imports/studio3d/q3dsstudio3ditem.cpp b/src/imports/studio3d/q3dsstudio3ditem.cpp
index ce7a169..25a4d8c 100644
--- a/src/imports/studio3d/q3dsstudio3ditem.cpp
+++ b/src/imports/studio3d/q3dsstudio3ditem.cpp
@@ -94,6 +94,59 @@ QT_BEGIN_NAMESPACE
     }
     \endqml
 
+    \section2 Alternative usage
+
+    The above example shows the 3D content in the Studio3D item. Qt 3D Studio
+    presentations consist of one or more layers, each of which is a 3D scene
+    with its own camera and lights. The output of each layer is then composed
+    together into a final image, taking layer position, size, and blending into
+    account. Studio3D shows this final image by default.
+
+    In many cases it can be beneficial to follow a different model: instead of
+    displaying the final, composed content in a single Studio3D item, it is
+    also possible to manage the Qt 3D Studio layers individually as Qt Quick
+    items, thus moving the layer composition into Qt Quick's domain. The 3D
+    engine's final image is not generated at all in this case. The key enabler
+    for this approach is the \l View3D type.
+
+    \qml
+    Studio3D {
+        id: studio3D
+        Presentation {
+            source: "qrc:///presentation.uia"
+            SceneElement {
+                id: scene
+                elementPath: "Scene"
+                currentSlideIndex: 2
+            }
+            Element {
+                id: textLabel
+                elementPath: "Scene.Layer.myLabel"
+            }
+        }
+        onRunningChanged: {
+            console.log("Presentation ready!");
+        }
+    }
+
+    View3D {
+        engine: studio3D
+        source: "LayerName"
+        anchors.fill: parent
+    }
+    \endqml
+
+    In this modified example the Studio3D item does not display any content,
+    while the View3D item displays only the content of a single layer,
+    referenced by the name set in the Qt 3D Studio application. This approach
+    enables creating interfaces where multiple different pieces of 3D content
+    is blended with the 2D user interface, instead of being restricted to a
+    single rectangular area defined by the Studio3D item.
+
+    \note Multiple Studio3D items should be avoided. Prefer using \l View3D
+    whenever there is a need to display 3D content in multiple areas of the
+    screen.
+
     \section2 Controlling the presentation
 
     Like the example above suggests, Studio3D and the other types under the
@@ -117,7 +170,7 @@ QT_BEGIN_NAMESPACE
 
     \endlist
 
-    \sa Presentation
+    \sa View3D, Presentation
 */
 
 /*!
diff --git a/src/imports/studio3d/q3dsstudio3dview.cpp b/src/imports/studio3d/q3dsstudio3dview.cpp
index 0f48423..48a9f4a 100644
--- a/src/imports/studio3d/q3dsstudio3dview.cpp
+++ b/src/imports/studio3d/q3dsstudio3dview.cpp
@@ -45,8 +45,7 @@ QT_BEGIN_NAMESPACE
     \ingroup 3dstudioruntime2
     \inherits Item
     \keyword View3D
-
-    \internal
+    \since Qt 3D Studio 2.2
 
     \brief An item rendering the contents of a single layer from a Qt 3D Studio presentation.
 
diff --git a/src/runtime/api/q3dspresentation.cpp b/src/runtime/api/q3dspresentation.cpp
index 51ba0fe..6c502e1 100644
--- a/src/runtime/api/q3dspresentation.cpp
+++ b/src/runtime/api/q3dspresentation.cpp
@@ -746,6 +746,10 @@ void Q3DSPresentationPrivate::registerInlineQmlSubPresentations(const QVector<Q3
     property has no effect.
 
     Default value is \c{false}.
+
+    \note This property has no effect when using \l View3D items in the Qt
+    Quick scene, because the profile views are managed by Qt Quick, not the 3D
+    engine then. Use \l Studio3DProfiler in that case.
 */
 
 /*!
@@ -754,6 +758,10 @@ void Q3DSPresentationPrivate::registerInlineQmlSubPresentations(const QVector<Q3
     Controls the scale factor of the in-scene debug and profile views.
 
     The default value is 1.0.
+
+    \note This property has no effect when using \l View3D items in the Qt
+    Quick scene, because the profile views are managed by Qt Quick, not the 3D
+    engine then. Use \l Studio3DProfiler in that case.
 */
 
 /*!
diff --git a/src/runtime/api/q3dsviewersettings.cpp b/src/runtime/api/q3dsviewersettings.cpp
index 3d4f3fe..d2d488c 100644
--- a/src/runtime/api/q3dsviewersettings.cpp
+++ b/src/runtime/api/q3dsviewersettings.cpp
@@ -125,6 +125,10 @@ QColor Q3DSViewerSettings::matteColor() const
     property has no effect.
 
     Default value is \c{false}.
+
+    \note This property has no effect when using \l View3D items in the Qt
+    Quick scene, because the profile views are managed by Qt Quick, not the 3D
+    engine then. Use \l Studio3DProfiler in that case.
 */
 bool Q3DSViewerSettings::isShowingRenderStats() const
 {
@@ -272,6 +276,11 @@ Q3DSViewportSettings *Q3DSViewerSettingsPrivate::createViewportSettingsProxy()
 
     This type provides properties to define presentation independent viewer settings.
 
+    \note ViewerSettings are only applicable when \l Studio3D is used in the
+    default mode, showing the final, composed image from the Qt 3D Studio
+    renderer. ViewerSettings has no effect when using \l View3D items to
+    render layers individually.
+
     \sa Studio3D
 */
 
diff --git a/src/runtime/profileui/q3dsimguiitem.cpp b/src/runtime/profileui/q3dsimguiitem.cpp
index a7d85c8..0dec9a2 100644
--- a/src/runtime/profileui/q3dsimguiitem.cpp
+++ b/src/runtime/profileui/q3dsimguiitem.cpp
@@ -50,8 +50,7 @@ QT_BEGIN_NAMESPACE
     \ingroup 3dstudioruntime2
     \inherits Item
     \keyword Studio3DProfiler
-
-    \internal
+    \since Qt 3D Studio 2.2
 
     \brief An item rendering profile and debug views in Qt Quick
 
diff --git a/tests/manual/manual.pro b/tests/manual/manual.pro
index 28fa4f4..3305255 100644
--- a/tests/manual/manual.pro
+++ b/tests/manual/manual.pro
@@ -7,7 +7,6 @@ qtHaveModule(widgets) {
 }
 qtHaveModule(quick) {
     SUBDIRS += \
-        layersinquick \
-        pureqml3d \
-        qml3dapi
+        qml3dapi \
+        pureqml3d
 }