QCameraLens: allow specify projection with frustrum

Also added doc

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

4 files changed, 164 insertions, 9 deletions

diff --git a/src/core/core-components/qcameralens.cpp b/src/core/core-components/qcameralens.cpp
index fde9d16ad..23449d6cb 100644
--- a/src/core/core-components/qcameralens.cpp
+++ b/src/core/core-components/qcameralens.cpp
@@ -59,7 +59,6 @@ QCameraLensPrivate::QCameraLensPrivate(QCameraLens *qq)
 {
 }
 
-
 QCameraLens::QCameraLens(QNode *parent)
     : QComponent(*new QCameraLensPrivate(this), parent)
 {
@@ -83,7 +82,13 @@ void QCameraLens::copy(const QNode *ref)
     d_func()->m_projectionMatrix = lens->d_func()->m_projectionMatrix;
 }
 
-/*! \internal */
+/*! \class Qt3D::QCameraLens
+ *
+ * \brief Qt3D::QCameraLens specifies the projection matrix that will be used to
+ * define a Camera for a 3D scene.
+ *
+ *  \since 5.5
+ */
 QCameraLens::QCameraLens(QCameraLensPrivate &dd, QNode *parent)
     : QComponent(dd, parent)
 {
@@ -91,6 +96,13 @@ QCameraLens::QCameraLens(QCameraLensPrivate &dd, QNode *parent)
     d->updateOrthogonalProjection();
 }
 
+/*!
+ * Sets the lens' projection type \a projectionType.
+ *
+ * \note Qt3D::QCameraLens::Frustum and
+ * Qt3D::QCameraLens::PerspectiveProjection are two different ways of
+ * specifying the same projection.
+ */
 void QCameraLens::setProjectionType(QCameraLens::ProjectionType projectionType)
 {
     Q_D(QCameraLens);
@@ -101,15 +113,22 @@ void QCameraLens::setProjectionType(QCameraLens::ProjectionType projectionType)
     }
 }
 
+/*!
+ * Returns the lens' projection type.
+ */
 QCameraLens::ProjectionType QCameraLens::projectionType() const
 {
     Q_D(const QCameraLens);
     return d->m_projectionType;
 }
 
-void QCameraLens::setOrthographicProjection( float left, float right,
-                                             float bottom, float top,
-                                             float nearPlane, float farPlane )
+/*!
+ * Defines an orthographic projection based on \a left, \a right, \a bottom, \a
+ * top, \a nearPlane, \a farPlane.
+ */
+void QCameraLens::setOrthographicProjection(float left, float right,
+                                            float bottom, float top,
+                                            float nearPlane, float farPlane)
 {
     Q_D(QCameraLens);
     bool block = blockNotifications(true);
@@ -124,8 +143,33 @@ void QCameraLens::setOrthographicProjection( float left, float right,
     d->updateProjectionMatrix();
 }
 
-void QCameraLens::setPerspectiveProjection( float fieldOfView, float aspectRatio,
-                                            float nearPlane, float farPlane )
+/*!
+ * Defines an orthographic projection based on \a left, \a right, \a bottom, \a
+ * top, \a nearPlane, \a farPlane.
+ */
+void QCameraLens::setFrustumProjection(float left, float right,
+                                       float bottom, float top,
+                                       float nearPlane, float farPlane)
+{
+    Q_D(QCameraLens);
+    bool block = blockNotifications(true);
+    setLeft(left);
+    setRight(right);
+    setBottom(bottom);
+    setTop(top);
+    setNearPlane(nearPlane);
+    setFarPlane(farPlane);
+    setProjectionType(FrustumProjection);
+    blockNotifications(block);
+    d->updateProjectionMatrix();
+}
+
+/*!
+ * Defines a perspective projection based on \a fieldOfView, \a aspectRatio, \a
+ * nearPlane, \a farPlane.
+ */
+void QCameraLens::setPerspectiveProjection(float fieldOfView, float aspectRatio,
+                                           float nearPlane, float farPlane)
 {
     Q_D(QCameraLens);
     bool block = blockNotifications(true);
@@ -138,6 +182,10 @@ void QCameraLens::setPerspectiveProjection( float fieldOfView, float aspectRatio
     d->updateProjectionMatrix();
 }
 
+/*!
+ * Sets the projection's near plane to \a nearPlane. This triggers a projection
+ * matrix update.
+ */
 void QCameraLens::setNearPlane(float nearPlane)
 {
     Q_D(QCameraLens);
@@ -148,12 +196,19 @@ void QCameraLens::setNearPlane(float nearPlane)
     d->updateProjectionMatrix();
 }
 
+/*!
+ * Returns the projection's near plane.
+ */
 float QCameraLens::nearPlane() const
 {
     Q_D(const QCameraLens);
     return d->m_nearPlane;
 }
 
+/*!
+ * Sets the projection's far plane to \a farPlane. This triggers a projection
+ * matrix update.
+ */
 void QCameraLens::setFarPlane(float farPlane)
 {
     Q_D(QCameraLens);
@@ -164,12 +219,22 @@ void QCameraLens::setFarPlane(float farPlane)
     d->updateProjectionMatrix();
 }
 
+/*!
+ * Returns the projection's far plane.
+ */
 float QCameraLens::farPlane() const
 {
     Q_D(const QCameraLens);
     return d->m_farPlane;
 }
 
+/*!
+ * Sets the projection's field of view to \a fieldOfView degrees. This triggers
+ * a projection matrix update.
+ *
+ * \note this has no effect if the projection type is not
+ * Qt3D::QCameraLens::PerspectiveProjection.
+ */
 void QCameraLens::setFieldOfView(float fieldOfView)
 {
     Q_D(QCameraLens);
@@ -180,12 +245,25 @@ void QCameraLens::setFieldOfView(float fieldOfView)
     d->updateProjectionMatrix();
 }
 
+/*!
+ * Returns the projection's field of view in degrees.
+ *
+ * \note: The return value may be undefined if the projection type is not
+ * Qt3D::QCameraLens::PerspectiveProjection.
+ */
 float QCameraLens::fieldOfView() const
 {
     Q_D(const QCameraLens);
     return d->m_fieldOfView;
 }
 
+/*!
+ * Sets the projection's aspect ratio to \a aspectRatio. This triggers a projection
+ * matrix update.
+ *
+ * \note this has no effect if the projection type is not
+ * Qt3D::QCameraLens::PerspectiveProjection.
+ */
 void QCameraLens::setAspectRatio(float aspectRatio)
 {
     Q_D(QCameraLens);
@@ -196,12 +274,25 @@ void QCameraLens::setAspectRatio(float aspectRatio)
     d->updateProjectionMatrix();
 }
 
+/*!
+ * Returns the projection's aspect ratio.
+ *
+ * \note: The return value may be undefined if the projection type is not
+ * Qt3D::QCameraLens::PerspectiveProjection.
+ */
 float QCameraLens::aspectRatio() const
 {
     Q_D(const QCameraLens);
     return d->m_aspectRatio;
 }
 
+/*!
+ * Sets the projection's lower left window coordinate to \a left. This
+ * triggers a projection matrix update.
+ *
+ * \note this has no effect if the projection type is
+ * Qt3D::QCameraLens::PerspectiveProjection.
+ */
 void QCameraLens::setLeft(float left)
 {
     Q_D(QCameraLens);
@@ -212,12 +303,25 @@ void QCameraLens::setLeft(float left)
     d->updateProjectionMatrix();
 }
 
+/*!
+ * Returns the lower left window coordinate of the projection.
+ *
+ * \note The return value may be undefined if the projection type is
+ * Qt3D::QCameraLens::PerspectiveProjection.
+ */
 float QCameraLens::left() const
 {
     Q_D(const QCameraLens);
     return d->m_left;
 }
 
+/*!
+ * Sets the projection's upper right window coordinate to \a right. This triggers
+ * a projection matrix update.
+ *
+ * \note this has no effect if the projection type is
+ * Qt3D::QCameraLens::PerspectiveProjection.
+ */
 void QCameraLens::setRight(float right)
 {
     Q_D(QCameraLens);
@@ -228,12 +332,25 @@ void QCameraLens::setRight(float right)
     d->updateProjectionMatrix();
 }
 
+/*!
+ * Returns the upper right window coordinate of the projection.
+ *
+ * \note The return value may be undefined if the projection type is
+ * Qt3D::QCameraLens::PerspectiveProjection.
+ */
 float QCameraLens::right() const
 {
     Q_D(const QCameraLens);
     return d->m_right;
 }
 
+/*!
+ * Sets the projection's bottom window coordinate to \a bottom. This triggers a
+ * projection matrix update.
+ *
+ * \note this has no effect if the projection type is
+ * Qt3D::QCameraLens::PerspectiveProjection.
+ */
 void QCameraLens::setBottom(float bottom)
 {
     Q_D(QCameraLens);
@@ -244,12 +361,25 @@ void QCameraLens::setBottom(float bottom)
     d->updateProjectionMatrix();
 }
 
+/*!
+ * Returns the bottom window coordinate of the projection.
+ *
+ * \note The return value may be undefined if the projection type is
+ * Qt3D::QCameraLens::PerspectiveProjection.
+ */
 float QCameraLens::bottom() const
 {
     Q_D(const QCameraLens);
     return d->m_bottom;
 }
 
+/*!
+ * Sets the projection's top window coordinate to \a top. This triggers a
+ * projection matrix update.
+ *
+ * \note this has no effect if the projection type is
+ * Qt3D::QCameraLens::PerspectiveProjection.
+ */
 void QCameraLens::setTop(float top)
 {
     Q_D(QCameraLens);
@@ -260,12 +390,21 @@ void QCameraLens::setTop(float top)
     d->updateProjectionMatrix();
 }
 
+/*!
+ * Returns the bottom window coordinate of the projection.
+ *
+ * \note The return value may be undefined if the projection type is
+ * Qt3D::QCameraLens::PerspectiveProjection.
+ */
 float QCameraLens::top() const
 {
     Q_D(const QCameraLens);
     return d->m_top;
 }
 
+/*!
+ * Returns the projection matrix.
+ */
 QMatrix4x4 QCameraLens::projectionMatrix() const
 {
     Q_D(const QCameraLens);
diff --git a/src/core/core-components/qcameralens.h b/src/core/core-components/qcameralens.h
index 8e1c69fed..54742ef26 100644
--- a/src/core/core-components/qcameralens.h
+++ b/src/core/core-components/qcameralens.h
@@ -71,7 +71,8 @@ public:
 
     enum ProjectionType {
         OrthogonalProjection,
-        PerspectiveProjection
+        PerspectiveProjection,
+        FrustumProjection
     };
 
     void setProjectionType(ProjectionType projectionType);
@@ -107,6 +108,10 @@ public:
                                    float bottom, float top,
                                    float nearPlane, float farPlane);
 
+    void setFrustumProjection(float left, float right,
+                              float bottom, float top,
+                              float nearPlane, float farPlane);
+
     void setPerspectiveProjection(float fieldOfView, float aspect,
                                   float nearPlane, float farPlane);
 
diff --git a/src/core/core-components/qcameralens_p.h b/src/core/core-components/qcameralens_p.h
index f0c810357..10d1aaf8e 100644
--- a/src/core/core-components/qcameralens_p.h
+++ b/src/core/core-components/qcameralens_p.h
@@ -62,6 +62,9 @@ public:
         case QCameraLens::PerspectiveProjection:
             updatePerpectiveProjection();
             break;
+        case QCameraLens::FrustumProjection:
+            updateFrustumProjection();
+            break;
         }
     }
 
@@ -98,6 +101,14 @@ private:
         m_projectionMatrix.ortho(m_left, m_right, m_bottom, m_top, m_nearPlane, m_farPlane);
         Q_EMIT q->projectionMatrixChanged();
     }
+
+    inline void updateFrustumProjection()
+    {
+        Q_Q(QCameraLens);
+        m_projectionMatrix.setToIdentity();
+        m_projectionMatrix.frustum(m_left, m_right, m_bottom, m_top, m_nearPlane, m_farPlane);
+        Q_EMIT q->projectionMatrixChanged();
+    }
 };
 
 } // namespace Qt3D
diff --git a/src/render/backend/jobs/renderviewjob.cpp b/src/render/backend/jobs/renderviewjob.cpp
index 53065245e..9115b90ed 100644
--- a/src/render/backend/jobs/renderviewjob.cpp
+++ b/src/render/backend/jobs/renderviewjob.cpp
@@ -67,7 +67,7 @@ void RenderViewJob::run()
     setRenderViewConfigFromFrameGraphLeafNode(renderView, m_fgLeaf);
 
     // Build RenderCommand should perform the culling as we have no way to determine
-    // if a child has a mesh in the view frustrum while its parent isn't contained in it.
+    // if a child has a mesh in the view frustum while its parent isn't contained in it.
     if (!renderView->noDraw())
         renderView->buildRenderCommands(m_renderer->renderSceneRoot());