Enhance docs for Studio3DProfiler and View3D

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

1 files changed, 57 insertions, 0 deletions

diff --git a/src/imports/studio3d/q3dsstudio3ditem.cpp b/src/imports/studio3d/q3dsstudio3ditem.cpp
index 020a8c6..283f56e 100644
--- a/src/imports/studio3d/q3dsstudio3ditem.cpp
+++ b/src/imports/studio3d/q3dsstudio3ditem.cpp
@@ -71,6 +71,8 @@ QT_BEGIN_NAMESPACE
     \qml
     Studio3D {
         id: studio3D
+        anchors.fill: parent
+
         Presentation {
             source: "qrc:///presentation.uia"
             SceneElement {
@@ -92,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
@@ -114,6 +169,8 @@ QT_BEGIN_NAMESPACE
     Component nodes via Presentation::goToTime(), \l SceneElement, and \l DataInput.
 
     \endlist
+
+    \sa View3D, Presentation
 */
 
 /*!