Qt3DExtra materials documentation fixes

Materials that were moved to Qt3DExtras were still part of Qt3DRender
according to the documentation.
Also added documentation for QML versions.

Change-Id: Icd918599cf9a97a14e65f38a28309316a5f504dd
Reviewed-by: Antti Määttä <antti.maatta@qt.io>
Reviewed-by: Paul Lemire <paul.lemire@kdab.com>

1 files changed, 568 insertions, 0 deletions

diff --git a/src/doc/src/qmlextramaterials.qdoc b/src/doc/src/qmlextramaterials.qdoc
new file mode 100644
index 000000000..48f1a2326
--- /dev/null
+++ b/src/doc/src/qmlextramaterials.qdoc
@@ -0,0 +1,568 @@
+/****************************************************************************
+**
+** Copyright (C) 2016 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of the Qt3D module of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** 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 Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 3 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL3 included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 3 requirements
+** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 2.0 or (at your option) the GNU General
+** Public license version 3 or any later version approved by the KDE Free
+** Qt Foundation. The licenses are as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
+** included in the packaging of this file. Please review the following
+** information to ensure the GNU General Public License requirements will
+** be met: https://www.gnu.org/licenses/gpl-2.0.html and
+** https://www.gnu.org/licenses/gpl-3.0.html.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \qmltype DiffuseMapMaterial
+    \inqmlmodule Qt3D.Extras
+    \brief The DiffuseMapMaterial provides a default implementation of the phong lighting effect
+    where the diffuse light component is read from a texture map.
+    \since 5.7
+    \inherits Qt3D.Render::Material
+
+    The specular lighting effect is based on the combination of 3 lighting components ambient,
+    diffuse and specular. The relative strengths of these components are controlled by means of
+    their reflectivity coefficients which are modelled as RGB triplets:
+
+    \list
+    \li Ambient is the color that is emitted by an object without any other light source.
+    \li Diffuse is the color that is emitted for rought surface reflections with the lights.
+    \li Specular is the color emitted for shiny surface reflections with the lights.
+    \li The shininess of a surface is controlled by a float property.
+    \endlist
+
+    This material uses an effect with a single render pass approach and performs per fragment
+    lighting. Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.
+*/
+/*!
+    \qmlproperty color DiffuseMapMaterial::ambient
+
+    Holds the current ambient color.
+*/
+/*!
+    \qmlproperty color DiffuseMapMaterial::specular
+
+    Holds the current specular color.
+*/
+/*!
+    \qmlproperty real DiffuseMapMaterial::shininess
+
+    Holds the current shininess.
+*/
+/*!
+    \qmlproperty real DiffuseMapMaterial::textureScale
+
+    Holds the current texture scale. It is applied as a multiplier to texture
+    coordinates at render time. Defaults to 1.0.
+*/
+/*!
+    \qmlproperty TextureImage DiffuseMapMaterial::diffuse
+
+    Holds the current texture used as the diffuse map.
+
+    By default, the diffuse texture has the following properties:
+
+    \list
+        \li Linear minification and magnification filters
+        \li Linear mipmap with mipmapping enabled
+        \li Repeat wrap mode
+        \li Maximum anisotropy of 16.0
+    \endlist
+*/
+
+/*!
+    \qmltype DiffuseSpecularMapMaterial
+    \inqmlmodule Qt3D.Extras
+    \brief The DiffuseSpecularMapMaterial provides a default implementation of the phong lighting
+    effect where the diffuse and specular light components are read from texture maps.
+    \since 5.7
+    \inherits Qt3D.Render::Material
+
+    The specular lighting effect is based on the combination of 3 lighting components ambient,
+    diffuse and specular. The relative strengths of these components are controlled by means of
+    their reflectivity coefficients which are modelled as RGB triplets:
+
+    \list
+    \li Ambient is the color that is emitted by an object without any other light source.
+    \li Diffuse is the color that is emitted for rought surface reflections with the lights.
+    \li Specular is the color emitted for shiny surface reflections with the lights.
+    \li The shininess of a surface is controlled by a float property.
+    \endlist
+
+    This material uses an effect with a single render pass approach and performs per fragment
+    lighting. Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.
+*/
+/*!
+    \qmlproperty color DiffuseSpecularMapMaterial::ambient
+
+    Holds the current ambient color.
+*/
+/*!
+    \qmlproperty TextureImage DiffuseSpecularMapMaterial::diffuse
+
+    Holds the current diffuse map texture.
+
+    By default, the diffuse texture has the following properties:
+
+    \list
+        \li Linear minification and magnification filters
+        \li Linear mipmap with mipmapping enabled
+        \li Repeat wrap mode
+        \li Maximum anisotropy of 16.0
+    \endlist
+*/
+/*!
+    \qmlproperty TextureImage DiffuseSpecularMapMaterial::specular
+
+    Holds the current specular map texture.
+
+    By default, the specular texture has the following properties:
+
+    \list
+        \li Linear minification and magnification filters
+        \li Linear mipmap with mipmapping enabled
+        \li Repeat wrap mode
+        \li Maximum anisotropy of 16.0
+    \endlist
+*/
+/*!
+    \qmlproperty real DiffuseSpecularMapMaterial::shininess
+
+    Holds the current shininess.
+*/
+/*!
+    \qmlproperty real DiffuseSpecularMapMaterial::textureScale
+
+    Holds the current texture scale. It is applied as a multiplier to texture
+    coordinates at render time. Defaults to 1.0.
+*/
+
+/*!
+    \qmltype GoochMaterial
+    \inqmlmodule Qt3D.Extras
+    \brief The GoochMaterial provides a material that implements the Gooch
+    shading model, popular in CAD and CAM applications.
+    \since 5.7
+    \inherits Qt3D.Render::Material
+
+    The Gooch lighting model uses both color and brightness to help show the
+    curvature of 3D surfaces. This is often better than models such as Phong
+    that rely purely upon changes in brightness. In situations such as in CAD
+    and CAM applications where photorealism is not a goal, the Gooch shading
+    model in conjunction with some kind of silhouette edge inking is a popular
+    solution.
+
+    The Gooch lighting model is explained fully in the \l{original Gooch
+    paper}. The Gooch model mixes a diffuse object color with a user-provided
+    cool color and warm color to produce the end points of a color ramp that is
+    used to shade the object based upon the cosine of the angle between the
+    vector from the fragment to the light source and the fragment's normal
+    vector. Optionally, a specular highlight can be added on top. The relative
+    contributions to the cool and warm colors by the diffuse color are
+    controlled by the alpha and beta properties respecitvely.
+
+    This material uses an effect with a single render pass approach and
+    performs per fragment lighting. Techniques are provided for OpenGL 2,
+    OpenGL 3 or above as well as OpenGL ES 2.
+*/
+/*!
+    \qmlproperty color GoochMaterial::diffuse
+
+    Holds the current diffuse color.
+*/
+/*!
+    \qmlproperty color GoochMaterial::specular
+
+    Holds the current specular color.
+*/
+/*!
+    \qmlproperty color GoochMaterial::coolColor
+
+    Holds the current coolColor color.
+*/
+/*!
+    \qmlproperty color GoochMaterial::warmColor
+
+    Holds the current warmColor color.
+*/
+/*!
+    \qmlproperty real GoochMaterial::alpha
+
+    Holds the current alpha value. The start point of the color ramp
+    used by the Gooch shader is calculated as {c = cool + alpha * diffuse}.
+*/
+/*!
+    \qmlproperty real GoochMaterial::beta
+
+    Holds the current beta value. The start point of the color ramp
+    used by the Gooch shader is calculated as {c = warm + beta * diffuse}.
+*/
+/*!
+    \qmlproperty real GoochMaterial::shininess
+
+    Holds the current shininess value. Higher values of shininess result in
+    a smaller and brighter highlight.
+*/
+
+/*!
+    \qmltype NormalDiffuseMapAlphaMaterial
+    \inqmlmodule Qt3D.Extras
+    \brief The NormalDiffuseMapAlphaMaterial provides a specialization of NormalDiffuseMapMaterial
+    with alpha coverage and a depth test performed in the rendering pass.
+    \since 5.7
+    \inherits Qt3D.Render::Material
+
+    The specular lighting effect is based on the combination of 3 lighting components ambient,
+    diffuse and specular. The relative strengths of these components are controlled by means of
+    their reflectivity coefficients which are modelled as RGB triplets:
+
+    \list
+    \li Ambient is the color that is emitted by an object without any other light source.
+    \li Diffuse is the color that is emitted for rought surface reflections with the lights.
+    \li Specular is the color emitted for shiny surface reflections with the lights.
+    \li The shininess of a surface is controlled by a float property.
+    \endlist
+
+    This material uses an effect with a single render pass approach and performs per fragment
+    lighting. Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.
+*/
+/*!
+    \qmlproperty color NormalDiffuseMapAlphaMaterial::ambient
+
+    Holds the current ambient color.
+*/
+/*!
+    \qmlproperty TextureImage NormalDiffuseMapAlphaMaterial::diffuse
+
+    Holds the current diffuse map texture.
+
+    By default, the diffuse texture has the following properties:
+
+    \list
+        \li Linear minification and magnification filters
+        \li Linear mipmap with mipmapping enabled
+        \li Repeat wrap mode
+        \li Maximum anisotropy of 16.0
+    \endlist
+*/
+/*!
+    \qmlproperty color NormalDiffuseMapAlphaMaterial::specular
+
+    Holds the current specular color.
+*/
+/*!
+    \qmlproperty TextureImage NormalDiffuseMapAlphaMaterial::normal
+
+    Holds the current normal map texture.
+
+    By default, the normal texture has the following properties:
+
+    \list
+        \li Linear minification and magnification filters
+        \li Repeat wrap mode
+        \li Maximum anisotropy of 16.0
+    \endlist
+*/
+/*!
+    \qmlproperty real NormalDiffuseMapAlphaMaterial::shininess
+
+    Holds the current shininess.
+*/
+/*!
+    \qmlproperty real NormalDiffuseMapAlphaMaterial::textureScale
+
+    Holds the current texture scale. It is applied as a multiplier to texture
+    coordinates at render time. Defaults to 1.0.
+*/
+
+/*!
+    \qmltype NormalDiffuseMapMaterial
+    \inqmlmodule Qt3D.Extras
+    \brief The NormalDiffuseMapMaterial provides a default implementation of the phong lighting
+    and bump effect where the diffuse light component is read from a texture map and the normals of
+    the mesh being rendered from a normal texture map.
+    \since 5.7
+    \inherits Qt3D.Render::Material
+
+    The specular lighting effect is based on the combination of 3 lighting components ambient,
+    diffuse and specular. The relative strengths of these components are controlled by means of
+    their reflectivity coefficients which are modelled as RGB triplets:
+
+    \list
+    \li Ambient is the color that is emitted by an object without any other light source.
+    \li Diffuse is the color that is emitted for rought surface reflections with the lights.
+    \li Specular is the color emitted for shiny surface reflections with the lights.
+    \li The shininess of a surface is controlled by a float property.
+    \endlist
+
+    This material uses an effect with a single render pass approach and performs per fragment
+    lighting. Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.
+*/
+/*!
+    \qmlproperty color NormalDiffuseMapMaterial::ambient
+
+    Holds the current ambient color.
+*/
+/*!
+    \qmlproperty TextureImage NormalDiffuseMapMaterial::diffuse
+
+    Holds the current diffuse map texture.
+
+    By default, the diffuse texture has the following properties:
+
+    \list
+        \li Linear minification and magnification filters
+        \li Linear mipmap with mipmapping enabled
+        \li Repeat wrap mode
+        \li Maximum anisotropy of 16.0
+    \endlist
+*/
+/*!
+    \qmlproperty color NormalDiffuseMapMaterial::specular
+
+    Holds the current specular color.
+*/
+/*!
+    \qmlproperty TextureImage NormalDiffuseMapMaterial::normal
+
+    Holds the current normal map texture.
+
+    By default, the normal texture has the following properties:
+
+    \list
+        \li Linear minification and magnification filters
+        \li Repeat wrap mode
+        \li Maximum anisotropy of 16.0
+    \endlist
+*/
+/*!
+    \qmlproperty real NormalDiffuseMapMaterial::shininess
+
+    Holds the current shininess.
+*/
+/*!
+    \qmlproperty real NormalDiffuseMapMaterial::textureScale
+
+    Holds the current texture scale. It is applied as a multiplier to texture
+    coordinates at render time. Defaults to 1.0.
+*/
+
+/*!
+    \qmltype NormalDiffuseSpecularMapMaterial
+    \inqmlmodule Qt3D.Extras
+    \brief The NormalDiffuseSpecularMapMaterial provides a default implementation of the phong
+    lighting and bump effect where the diffuse and specular light components are read from texture
+    maps and the normals of the mesh being rendered from a normal texture map.
+    \since 5.7
+    \inherits Qt3D.Render::Material
+
+    The specular lighting effect is based on the combination of 3 lighting components ambient,
+    diffuse and specular. The relative strengths of these components are controlled by means of
+    their reflectivity coefficients which are modelled as RGB triplets:
+
+    \list
+    \li Ambient is the color that is emitted by an object without any other light source.
+    \li Diffuse is the color that is emitted for rought surface reflections with the lights.
+    \li Specular is the color emitted for shiny surface reflections with the lights.
+    \li The shininess of a surface is controlled by a float property.
+    \endlist
+
+    This material uses an effect with a single render pass approach and performs per fragment
+    lighting. Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.
+*/
+/*!
+    \qmlproperty color NormalDiffuseSpecularMapMaterial::ambient
+
+    Holds the current ambient color.
+*/
+/*!
+    \qmlproperty TextureImage NormalDiffuseSpecularMapMaterial::diffuse
+
+    Holds the current diffuse map texture.
+
+    By default, the diffuse texture has the following properties:
+
+    \list
+        \li Linear minification and magnification filters
+        \li Linear mipmap with mipmapping enabled
+        \li Repeat wrap mode
+        \li Maximum anisotropy of 16.0
+    \endlist
+*/
+/*!
+    \qmlproperty TextureImage NormalDiffuseSpecularMapMaterial::specular
+
+    Holds the current specular map texture.
+
+    By default, the specular texture has the following properties:
+
+    \list
+        \li Linear minification and magnification filters
+        \li Linear mipmap with mipmapping enabled
+        \li Repeat wrap mode
+        \li Maximum anisotropy of 16.0
+    \endlist
+*/
+/*!
+    \qmlproperty TextureImage NormalDiffuseSpecularMapMaterial::normal
+
+    Holds the current normal map texture.
+
+    By default, the normal texture has the following properties:
+
+    \list
+        \li Linear minification and magnification filters
+        \li Repeat wrap mode
+        \li Maximum anisotropy of 16.0
+    \endlist
+*/
+/*!
+    \qmlproperty real NormalDiffuseSpecularMapMaterial::shininess
+
+    Holds the current shininess.
+*/
+/*!
+    \qmlproperty real NormalDiffuseSpecularMapMaterial::textureScale
+
+    Holds the current texture scale. It is applied as a multiplier to texture
+    coordinates at render time. Defaults to 1.0.
+*/
+
+/*!
+    \qmltype PerVertexColorMaterial
+    \inqmlmodule Qt3D.Extras
+    \brief The PerVertexColorMaterial class provides a default implementation for rendering the
+    color properties set for each vertex.
+    \since 5.7
+    \inherits Qt3D.Render::Material
+
+    This lighting effect is based on the combination of 2 lighting components ambient and diffuse.
+    Ambient is set by the vertex color.
+    Diffuse takes in account the normal distribution of each vertex.
+
+    \list
+    \li Ambient is the color that is emitted by an object without any other light source.
+    \li Diffuse is the color that is emitted for rough surface reflections with the lights
+    \endlist
+
+    This material uses an effect with a single render pass approach and forms  fragment lighting.
+    Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.
+*/
+
+/*!
+    \qmltype PhongAlphaMaterial
+    \inqmlmodule Qt3D.Extras
+    \brief The PhongAlphaMaterial class provides a default implementation of
+    the phong lighting effect with alpha.
+    \since 5.7
+    \inherits Qt3D.Render::Material
+
+    The phong lighting effect is based on the combination of 3 lighting components ambient, diffuse
+    and specular. The relative strengths of these components are controlled by means of their
+    reflectivity coefficients which are modelled as RGB triplets:
+
+    \list
+    \li Ambient is the color that is emitted by an object without any other light source.
+    \li Diffuse is the color that is emitted for rought surface reflections with the lights.
+    \li Specular is the color emitted for shiny surface reflections with the lights.
+    \li The shininess of a surface is controlled by a float property.
+    \li Alpha is the transparency of the surface between 0 (fully transparent) and 1 (opaque).
+    \endlist
+
+    This material uses an effect with a single render pass approach and performs per fragment
+    lighting. Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.
+*/
+/*!
+    \qmlproperty color PhongAlphaMaterial::ambient
+
+    Holds the current ambient color.
+*/
+/*!
+    \qmlproperty color PhongAlphaMaterial::diffuse
+
+    Holds the current diffuse color.
+*/
+/*!
+    \qmlproperty color PhongAlphaMaterial::specular
+
+    Holds the current specular color.
+*/
+/*!
+    \qmlproperty real PhongAlphaMaterial::shininess
+
+    Holds the current shininess.
+*/
+/*!
+    \qmlproperty real PhongAlphaMaterial::alpha
+
+    Holds the alpha component of the object which varies between 0 and 1.
+
+    The default value is 0.5.
+*/
+
+/*!
+    \qmltype PhongMaterial
+    \inqmlmodule Qt3D.Extras
+    \brief The PhongMaterial class provides a default implementation of the phong lighting effect.
+    \since 5.7
+    \inherits Qt3D.Render::Material
+
+    The phong lighting effect is based on the combination of 3 lighting components ambient, diffuse
+    and specular. The relative strengths of these components are controlled by means of their
+    reflectivity coefficients which are modelled as RGB triplets:
+
+    \list
+    \li Ambient is the color that is emitted by an object without any other light source.
+    \li Diffuse is the color that is emitted for rought surface reflections with the lights.
+    \li Specular is the color emitted for shiny surface reflections with the lights.
+    \li The shininess of a surface is controlled by a float property.
+    \endlist
+
+    This material uses an effect with a single render pass approach and performs per fragment
+    lighting. Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.
+*/
+/*!
+    \qmlproperty color PhongMaterial::ambient
+
+    Holds the current ambient color.
+*/
+/*!
+    \qmlproperty color PhongMaterial::diffuse
+
+    Holds the current diffuse color.
+*/
+/*!
+    \qmlproperty color PhongMaterial::specular
+
+    Holds the current specular color.
+*/
+/*!
+    \qmlproperty real PhongMaterial::shininess
+
+    Holds the current shininess.
+*/