Write docs for advanced custom material example

Also add it to highlighted items.

Task-number: QTBUG-60287
Change-Id: I87a6074bed171970b287c6cd934e6550d86e27e0
Reviewed-by: Sean Harmer <sean.harmer@kdab.com>

3 files changed, 90 insertions, 3 deletions

diff --git a/examples/qt3d/advancedcustommaterial/doc/images/advanced-custom-material.jpg b/examples/qt3d/advancedcustommaterial/doc/images/advanced-custom-material.jpg
new file mode 100644
index 000000000..98c4d8f68
--- /dev/null
+++ b/examples/qt3d/advancedcustommaterial/doc/images/advanced-custom-material.jpg
diff --git a/examples/qt3d/advancedcustommaterial/doc/src/advancedcustommaterial.qdoc b/examples/qt3d/advancedcustommaterial/doc/src/advancedcustommaterial.qdoc
new file mode 100644
index 000000000..eeb59f07b
--- /dev/null
+++ b/examples/qt3d/advancedcustommaterial/doc/src/advancedcustommaterial.qdoc
@@ -0,0 +1,84 @@
+/****************************************************************************
+**
+** Copyright (C) 2017 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:FDL$
+** 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 Free Documentation License Usage
+** Alternatively, this file may be used under the terms of the GNU Free
+** Documentation License version 1.3 as published by the Free Software
+** Foundation and appearing in the file included in the packaging of
+** this file. Please review the following information to ensure
+** the GNU Free Documentation License version 1.3 requirements
+** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \example advancedcustommaterial
+    \title Qt 3D: Advanced custom material QML Example
+    \ingroup qt3d-examples-qml
+    \brief Demonstrates creating advanced materials in Qt3D
+
+    \image advanced-custom-material.jpg
+
+    \e This example demonstrates creating advanced custom materials.
+
+    \include examples-run.qdocinc
+
+    \section1 Description
+
+    Advanced custom material example shows more complex shaders, and demonstrates controlling your
+    shader properties with QtQuick user interface and Animation. Water is a 3D mesh, that is
+    modeled and uv mapped inside Blender, and then brought into Scene 3D as an \c {.obj} file.
+    Shader properties that user can control, are defined in \l {advancedcustommaterial/WaterMaterial.qml}{WaterMaterial}.
+
+    \section1 Controls
+    \section2 Texture scale slider
+
+    Multiplies texture coordinates inside the vertex shader. Controls the size of the textures
+    on water surface.
+
+    \section2 Texture speed slider
+
+    Offsets values for texture coordinates which are animated in
+    \l {advancedcustommaterial/Water.qml}{Water.qml} and then passed to vertex shader.
+    Creates the effect of textures scrolling over the surface.
+
+    \section2 Specularity
+
+    Multiplies specular texture values inside fragment shader. Makes the water reflective.
+
+    \section2 Distortion
+
+    Multiplies the offset in red and blue channels of wave texture in fragment shader.
+    Makes the surface textures animate more randomly.
+
+    \section2 Normal amount
+
+    Multiplies the normal map values inside fragment shader. Controls the visibility of
+    smaller waves on the water surface.
+
+    \section2 Wave speed
+
+    Modifies the frequency of the sine wave inside vertex shader. Controls the speed of the waves.
+
+    \section2 Wave height
+
+    Multiplies the vertex \c {Y} position inside vertex shader. Controls the height of the waves.
+
+    \section2 Mesh rotation
+
+    Rotates the water mesh in \l {advancedcustommaterial/Water.qml}{Water.qml}.
+*/
diff --git a/src/doc/qt3d.qdocconf b/src/doc/qt3d.qdocconf
index f5bbadd8d..7da047ced 100644
--- a/src/doc/qt3d.qdocconf
+++ b/src/doc/qt3d.qdocconf
@@ -82,7 +82,8 @@ imagedirs   += images \
                ../../examples/qt3d/wireframe/doc/images \
                ../../examples/qt3d/audio-visualizer-qml/doc/images \
                ../../examples/qt3d/simplecustommaterial/doc/images \
-               ../../examples/qt3d/scene2d/doc/images
+               ../../examples/qt3d/scene2d/doc/images \
+               ../../examples/qt3d/advancedcustommaterial/doc/images
 
 Cpp.ignoretokens     += QT3DINPUTSHARED_EXPORT \
                         QT3DCORESHARED_EXPORT \
@@ -97,8 +98,10 @@ Cpp.ignoretokens     += QT3DINPUTSHARED_EXPORT \
 
 Cpp.ignoredirectives += Q_DECLARE_LOGGING_CATEGORY
 
-manifestmeta.highlighted.names = "Qt3D/Qt 3D: Audio Visualizer Example" \
-                                 "Qt3D/Qt 3D: Planets QML Example"
+manifestmeta.highlighted.names = \
+                "Qt3D/Qt 3D: Advanced custom material QML Example" \
+                "Qt3D/Qt 3D: Audio Visualizer Example" \
+                "Qt3D/Qt 3D: Planets QML Example"
 
 manifestmeta.thumbnail.names += "Qt3D/Qt 3D: Deferred Renderer C++ Example"