path: root/src/doc/src/qmlextramaterials.qdoc

/****************************************************************************
**
** 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.
*/