Document custom material texture Images

Add documentation for the changed custom material images.

Task-number: QT3DS-4187
Change-Id: I1075f58bd4000570641613b330971f4de6c1e832
Reviewed-by: Tomi Korpipää <tomi.korpipaa@qt.io>

6 files changed, 86 insertions, 6 deletions

diff --git a/doc/Src/whatsnew.qdoc b/doc/Src/whatsnew.qdoc
new file mode 100644
index 00000000..943b15c6
--- /dev/null
+++ b/doc/Src/whatsnew.qdoc
@@ -0,0 +1,56 @@
+/****************************************************************************
+**
+** Copyright (C) 2020 The Qt Company Ltd.
+** Contact: https://www.qt.io/licensing/
+**
+** This file is part of Qt 3D Studio.
+**
+** $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$
+**
+****************************************************************************/
+
+/*!
+
+\title What's New
+\page whatsnew.html
+
+\section1 New Features in Qt 3D Studio 2.8
+
+\section2 Image Filtering
+
+It is now possible to specify minification and magnification filters for the Images.
+This enables mipmapping for the textures.
+
+\section2 Custom Material and Effect Textures
+
+The Custom Material and Effect Textures have been converted to use Images. This means that the same
+image properties as previously only available for the standard materials can now be used to change
+the texture properties for the user-defined shaders. In order to support the image transformation,
+new per-texture uniforms and functions have been added to access transformed texture coordinates and
+texture sample. See \l {Custom Material Reference} how to use them in the shaders.
+
+When old presentation is opened for the first time with Studio Editor, it needs to convert
+the old texture paths into Images. If the presentation has sub-presentations they should be opened
+separately to ensure that the whole presentation has the same presentation version.
+
+Controlling the Custom property texture using API has been changed to reflect this change. They
+can now be controlled the same way as standard material textures. See \l {Custom Materials and Effects}
+for more details.
+
+*/
diff --git a/doc/src/00-concepts.qdoc b/doc/src/00-concepts.qdoc
index 61f1d1f4..88d02d74 100644
--- a/doc/src/00-concepts.qdoc
+++ b/doc/src/00-concepts.qdoc
@@ -34,6 +34,8 @@
 Qt 3D Studio is a compositing tool where you import 3D models, images and other assets to create
 interactive presentations, UIs and applications.
 
+See \l{What's New}{what's new} in Qt 3D Studio.
+
 \table
   \row
     \li
diff --git a/doc/src/03-studio/7-inspector-palette.qdoc b/doc/src/03-studio/7-inspector-palette.qdoc
index b55403f8..2958b0ac 100644
--- a/doc/src/03-studio/7-inspector-palette.qdoc
+++ b/doc/src/03-studio/7-inspector-palette.qdoc
@@ -858,9 +858,9 @@ The Inspector palette shows only a single property:
 \section1 Image Properties
 
 When image maps (e.g. Diffuse, Specular, Opacity, etc.) are applied to an animated material,
-a new element appears in the scene graph as a child of the material. This element represents
-the properties that control that image, allowing them to be animated over time. Selecting one of
-these images shows the image properties in the Inspector palette.
+custom material or effect, a new element appears in the scene graph as a child of the material.
+This element represents the properties that control that image, allowing them to be animated
+over time. Selecting one of these images shows the image properties in the Inspector palette.
 
 For basic and referenced materials, you need to first select the material in the scene graph. Then,
 right-click the map property name in the inspector and select \uicontrol {Open in inspector} from
diff --git a/doc/src/07-file-formats/5-custom-material-reference.qdoc b/doc/src/07-file-formats/5-custom-material-reference.qdoc
index 26cb56bd..8e46d7a6 100644
--- a/doc/src/07-file-formats/5-custom-material-reference.qdoc
+++ b/doc/src/07-file-formats/5-custom-material-reference.qdoc
@@ -497,6 +497,20 @@ void main()
 \note Previous versions stated that the closing parenthesis should not be added to the main function.
 This is no longer the case and the main function should add the closing parenthesis.
 
+\section2 Accessing Textures with Image Transformations
+
+When the custom material is generated, uniforms for the image transformation are also generated,
+as well as accessor functions to get the transformed coordinate and texture sample.
+
+For texture named \"basecolor\" the generated uniforms and functions are
+\badcode
+uniform vec3 basecolorTransformU;
+uniform vec3 basecolorTransformV;
+
+vec3 texcoordTransformed_basecolor(vec3 texcoord);
+vec4 sampleTransformed_basecolor(vec3 texcoord);
+\endcode
+
 \section2 Simple Custom Material Example
 
 \badcode
diff --git a/doc/src/07-file-formats/custom-materials-effects.qdoc b/doc/src/07-file-formats/custom-materials-effects.qdoc
index 66f5d8e7..a083546d 100644
--- a/doc/src/07-file-formats/custom-materials-effects.qdoc
+++ b/doc/src/07-file-formats/custom-materials-effects.qdoc
@@ -388,8 +388,14 @@ When some of the properties in custom materials or effects need to be adjusted d
 the \c setAttribute API is required. The usage may differ slightly from normal usage, depending on
 the property being controlled, as all of the properties in custom materials and effects are handled
 as dynamic properties.
+
+\note Since 2.8 the custom property textures use images and are controlled the same way as standard
+material textures.
+
+\omit
 For example, a texture is not handled as an image like it is when controlling it in standard
 material.
+\endomit
 \section3 Controlling a texture in standard material
 \badcode
 <presentation id>.setAttribute("<element path to texture>", "sourcepath", "<path to image>");
@@ -400,7 +406,7 @@ myPresentation.setAttribute("Scene.Layer.Sphere.Default_animatable.diffusemap",
 \endcode
 \section3 Controlling a texture in a custom material
 \badcode
-<presentation id>.setAttribute("<element path to material>", "<texture property name>", "<path to image>");
+<presentation id>.setAttribute("<element path to material>", "sourcepath", "<path to image>");
 \endcode
 With a material that has a metadata entry as follows:
 \badcode
@@ -412,6 +418,6 @@ With a material that has a metadata entry as follows:
 \endcode
 This is the way to control it:
 \badcode
-myPresentation.setAttribute("Scene.Layer.Sphere.MyMaterial_animatable", "diffuseTexture", "../maps/myTexture.png");
+myPresentation.setAttribute("Scene.Layer.Sphere.MyMaterial.diffuseTexture", "sourcepath", "../maps/myTexture.png");
 \endcode
 */
diff --git a/doc/src/10-best-practices/30-using-sub-presentations.qdoc b/doc/src/10-best-practices/30-using-sub-presentations.qdoc
index 21aff488..c8124d6b 100644
--- a/doc/src/10-best-practices/30-using-sub-presentations.qdoc
+++ b/doc/src/10-best-practices/30-using-sub-presentations.qdoc
@@ -129,7 +129,9 @@ To add a sub-presentation to a layer, do one of the following:
 One benefit of displaying a sub-presentation as a texture is that you can use Studio
 presentations and QML files to map the materials of objects in your presentation. You can apply
 sub-presentations to any map or image property of a material, i.e. diffuse maps, specular maps and
-displacement maps. This way you can for example create animated textures.
+displacement maps. This way you can for example create animated textures. For performance reasons
+it is best to disable mipmapping for subpresentation images by setting the minification filter to
+\c Nearest or \c Linear.
 
 To add a sub-presentation as a texture of a 3D object, do one of the following:
 \list