Expand Scene3D documentation

Change-Id: I2925920af001927ae9a843c7dde02ca48786834c
Reviewed-by: Sean Harmer <sean.harmer@kdab.com>

1 files changed, 28 insertions, 16 deletions

diff --git a/src/quick3d/imports/scene3d/scene3ditem.cpp b/src/quick3d/imports/scene3d/scene3ditem.cpp
index ffb1d9112..67785c1e8 100644
--- a/src/quick3d/imports/scene3d/scene3ditem.cpp
+++ b/src/quick3d/imports/scene3d/scene3ditem.cpp
@@ -101,7 +101,21 @@ namespace Qt3DRender {
     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.
+    premultiplied alpha. If multisampling is not required, it can be avoided
+    by setting the \l multisample property to \c false. In this case
+    Scene3D will render directly into the non-multisampled Framebuffer object.
+
+    If the scene to be rendered includes non-opaque materials, you may need to
+    modify those materials with custom blend arguments in order for them to be
+    rendered correctly. For example, if working with a \l PhongAlphaMaterial and
+    a scene with an opaque clear color, you will likely want to add:
+
+    \qml
+    sourceAlphaArg: BlendEquationArguments.Zero
+    destinationAlphaArg: BlendEquationArguments.One
+    \qml
+
+    to that material.
  */
 Scene3DItem::Scene3DItem(QQuickItem *parent)
     : QQuickItem(parent)
@@ -128,8 +142,12 @@ Scene3DItem::~Scene3DItem()
 /*!
     \qmlproperty list<string> Scene3D::aspects
 
-    \brief \TODO
-    */
+    The list of aspects that should be registered for the 3D scene.
+
+    For example, if the scene makes use of FrameAction, the \c "logic" aspect should be included in the list.
+
+    The \c "render" aspect is hardwired and does not need to be explicitly listed.
+*/
 QStringList Scene3DItem::aspects() const
 {
     return m_aspects;
@@ -140,7 +158,7 @@ QStringList Scene3DItem::aspects() const
 
     \default
 
-    \brief \TODO
+    The root entity of the 3D scene to be displayed.
  */
 Qt3DCore::QEntity *Scene3DItem::entity() const
 {
@@ -341,18 +359,7 @@ 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
-{
-    return m_multisample;
-}
-
-/*!
-    Enables or disables the usage of multisample renderbuffers based on \a enable.
+    \c true if a multisample render buffer is requested.
 
     By default multisampling is enabled. If the OpenGL implementation has no
     support for multisample renderbuffers or framebuffer blits, the request to
@@ -362,6 +369,11 @@ bool Scene3DItem::multisample() const
     and potentially slow initialization of framebuffers and other OpenGL
     resources.
  */
+bool Scene3DItem::multisample() const
+{
+    return m_multisample;
+}
+
 void Scene3DItem::setMultisample(bool enable)
 {
     if (m_multisample != enable) {