diff options
Diffstat (limited to 'src/doc/src')
| -rw-r--r-- | src/doc/src/qmlextracontrollers.qdoc | 170 | ||||
| -rw-r--r-- | src/doc/src/qmlextramaterials.qdoc | 568 |
2 files changed, 738 insertions, 0 deletions
diff --git a/src/doc/src/qmlextracontrollers.qdoc b/src/doc/src/qmlextracontrollers.qdoc new file mode 100644 index 000000000..737d0f823 --- /dev/null +++ b/src/doc/src/qmlextracontrollers.qdoc @@ -0,0 +1,170 @@ +/**************************************************************************** +** +** 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 FirstPersonCameraController + \inqmlmodule Qt3D.Extras + \brief The FirstPersonCameraController allows controlling the scene camera + from the first person perspective. + \since 5.7 + \inherits Qt3D.Core::Entity + + The FirstPersonCameraController allows controlling the scene camera from the first person + perspective. + + The controls are: + \table + \header + \li Input + \li Action + \row + \li Left mouse button + \li While the left mouse button is pressed, mouse movement along x-axis pans the camera and + movement along y-axis tilts it. + \row + \li Shift key + \li Turns the fine motion control active while pressed. Makes mouse pan and tilt less + sensitive. + \row + \li Arrow keys + \li Move the camera horizontally relative to camera viewport. + \row + \li Page up and page down keys + \li Move the camera vertically relative to camera viewport. + \endtable +*/ +/*! + \qmlproperty Camera FirstPersonCameraController::camera + + Holds the currently controlled camera. +*/ +/*! + \qmlproperty real FirstPersonCameraController::linearSpeed + + Holds the current linear speed of the camera controller. Linear speed determines the + movement speed of the camera. +*/ +/*! + \qmlproperty real FirstPersonCameraController::lookSpeed + + Holds the current look speed of the camera controller. The look speed determines the turn rate + of the camera pan and tilt. +*/ +/*! + \qmlproperty real FirstPersonCameraController::acceleration + + Holds the current acceleration. + Specifies the rate at which the camera linear speed increases when a key is held. + If the acceleration is negative, the linear speed stays constant. + Defaults to -1.0. +*/ +/*! + \qmlproperty real FirstPersonCameraController::deceleration + + Specifies the rate at which the camera linear speed decreases when a key is released. + If the deceleration is negative, the linear speed stays constant. + Defaults to -1.0. +*/ + +/*! + \qmltype OrbitCameraController + \inqmlmodule Qt3D.Extras + \brief The OrbitCameraController class allows controlling the scene camera along orbital path. + \since 5.7 + \inherits Qt3D.Core::Entity + + The OrbitCameraController class allows controlling the scene camera along orbital path. + + The controls are: + \table + \header + \li Input + \li Action + \row + \li Left mouse button + \li While the left mouse button is pressed, mouse movement along x-axis moves the camera + left and right and movement along y-axis moves it up and down. + \row + \li Right mouse button + \li While the right mouse button is pressed, mouse movement along x-axis pans the camera + around the camera view center and movement along y-axis tilts it around the camera + view center. + \row + \li Both left and right mouse button + \li While both the left and the right mouse button are pressed, mouse movement along y-axis + zooms the camera in and out without changing the view center. + \row + \li Arrow keys + \li Move the camera vertically and horizontally relative to camera viewport. + \row + \li Page up and page down keys + \li Move the camera forwards and backwards. + \row + \li Shift key + \li Changes the behavior of the up and down arrow keys to zoom the camera in and out + without changing the view center. The other movement keys are disabled. + \row + \li Alt key + \li Changes the behovior of the arrow keys to pan and tilt the camera around the view + center. Disables the page up and page down keys. + \endtable +*/ +/*! + \qmlproperty Camera OrbitCameraController::camera + + Holds the currently controlled camera. +*/ +/*! + \qmlproperty real OrbitCameraController::linearSpeed + + Holds the current linear speed of the camera controller. Linear speed determines the + movement speed of the camera. +*/ +/*! + \qmlproperty real OrbitCameraController::lookSpeed + + Holds the current look speed of the camera controller. The look speed determines the turn rate + of the camera pan and tilt. +*/ +/*! + \qmlproperty real OrbitCameraController::zoomLimit + + Holds the current zoom-in limit. The zoom-in limit determines how close to the view center + the camera can be zoomed. +*/ 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. +*/ |