From 01b2fc83188b63c7696bd391055eb2d0517d0019 Mon Sep 17 00:00:00 2001
From: Tomi Korpipaa <tomi.korpipaa@qt.io>
Date: Wed, 20 May 2020 13:25:46 +0300
Subject: Add documentation for controlling custom material properties
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes: QT3DS-4111
Change-Id: I880282c44c13f71c2861fe2aa932d0d921fd8a36
Reviewed-by: Miikka Heikkinen <miikka.heikkinen@qt.io>
Reviewed-by: Antti Määttä <antti.maatta@qt.io>
Reviewed-by: Tomi Korpipää <tomi.korpipaa@qt.io>
---
 .../07-file-formats/custom-materials-effects.qdoc  | 32 ++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/doc/src/07-file-formats/custom-materials-effects.qdoc b/doc/src/07-file-formats/custom-materials-effects.qdoc
index 6f333580..66f5d8e7 100644
--- a/doc/src/07-file-formats/custom-materials-effects.qdoc
+++ b/doc/src/07-file-formats/custom-materials-effects.qdoc
@@ -382,4 +382,36 @@ The first option results in
 \image materials-category-dummy.png
 and the seconds one results in
 \image materials-category-several.png
+
+\section2 Controlling Custom Properties
+When some of the properties in custom materials or effects need to be adjusted during run-time,
+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.
+For example, a texture is not handled as an image like it is when controlling it in standard
+material.
+\section3 Controlling a texture in standard material
+\badcode
+<presentation id>.setAttribute("<element path to texture>", "sourcepath", "<path to image>");
+\endcode
+For example:
+\badcode
+myPresentation.setAttribute("Scene.Layer.Sphere.Default_animatable.diffusemap", "sourcepath", "../maps/myTexture.png");
+\endcode
+\section3 Controlling a texture in a custom material
+\badcode
+<presentation id>.setAttribute("<element path to material>", "<texture property name>", "<path to image>");
+\endcode
+With a material that has a metadata entry as follows:
+\badcode
+<MetaData >
+    ...
+    <Property name="diffuseTexture" type="Texture" category="Material" formalName="Diffuse texture"/>
+    ...
+</MetaData>
+\endcode
+This is the way to control it:
+\badcode
+myPresentation.setAttribute("Scene.Layer.Sphere.MyMaterial_animatable", "diffuseTexture", "../maps/myTexture.png");
+\endcode
 */
-- 
cgit v1.2.3