Add documentation for the category property

Fixes: QT3DS-4112
Change-Id: I810496fea93e98bee849a73833456b5b7e7e2fcd
Reviewed-by: Antti Määttä <antti.maatta@qt.io>
Reviewed-by: Miikka Heikkinen <miikka.heikkinen@qt.io>

3 files changed, 42 insertions, 0 deletions

diff --git a/doc/Src/images/materials-category-dummy.png b/doc/Src/images/materials-category-dummy.png
new file mode 100644
index 00000000..5e66e737
--- /dev/null
+++ b/doc/Src/images/materials-category-dummy.png
diff --git a/doc/Src/images/materials-category-several.png b/doc/Src/images/materials-category-several.png
new file mode 100644
index 00000000..5ef32fb3
--- /dev/null
+++ b/doc/Src/images/materials-category-several.png
diff --git a/doc/src/07-file-formats/custom-materials-effects.qdoc b/doc/src/07-file-formats/custom-materials-effects.qdoc
index 646245ca..6f333580 100644
--- a/doc/src/07-file-formats/custom-materials-effects.qdoc
+++ b/doc/src/07-file-formats/custom-materials-effects.qdoc
@@ -170,6 +170,13 @@ A \c{property} element can have the following attributes:
     \li Text
     \li -
     \li Creates UI dropdown list.
+\row
+    \li category
+    \li Text
+    \li
+    \li Use to group material properties into separate categories. \note Required field for
+    materials. If this is not added, the property will not be displayed in the Inspector palette.
+    Adding category with empty string will not suffice.
 \endtable
 
 The only required attribute in the \c{<property>} element is \c{name}.
@@ -340,4 +347,39 @@ The element attributes are:
     \li Specifies if depth is written or not. With "true" depth is written, with "false" it's not.
 \endtable
 
+\section1 Things to Note
+
+\section2 Materials
+When creating a custom material with several properties, it is a good practice to use categories
+to separate them. If there is a need to be able to change the material for the mesh, at least one
+property needs to be added to \b Materials category. This will pull in \b {Material Type} and
+\b Shader properties into the Inspector palette.
+
+Consider a custom material with the following metadata:
+\badcode
+    <MetaData >
+        <Property category="ExampleMaterial" formalName="Environment Map" name="uEnvironmentTexture" description="Environment texture for the material" type="Texture" filter="linear" minfilter="linearMipmapLinear" clamp="repeat" usage="environment" default="./maps/materials/spherical_checker.png"/>
+        <Property category="ExampleMaterial" formalName="Enable Environment" name="uEnvironmentMappingEnabled" description="Enable environment mapping" type="Boolean" default="True"/>
+        <Property category="ExampleMaterial" formalName="Baked Shadow Map" name="uBakedShadowTexture" description="Baked shadow texture for the material" type="Texture" filter="linear" minfilter="linearMipmapLinear" clamp="repeat" usage="shadow" default="./maps/materials/shadow.png"/>
+        <Property category="ExampleMaterial" formalName="Shadow Mapping" name="uShadowMappingEnabled" description="Enable shadow mapping" type="Boolean" default="False"/>
+        <Property category="ExampleMaterial" formalName="Roughness" name="roughness" type="Float" min="0.0" max="1.0" default="0.3" description="Roughness of the material.\n0 = fully specular\n1 = fully diffuse"/>
+        <Property category="ExampleMaterial" formalName="Base color" name="base_color" type="Color" default="0.7 0.7 0.7" description="Color of the material"/>
+    </MetaData>
+\endcode
+and the same material with sensible categories defined, including \b {Material}:
+\badcode
+    <MetaData >
+        <Property category="Environment" formalName="Environment Map" name="uEnvironmentTexture" description="Environment texture for the material" type="Texture" filter="linear" minfilter="linearMipmapLinear" clamp="repeat" usage="environment" default="./maps/materials/spherical_checker.png"/>
+        <Property category="Environment" formalName="Enable Environment" name="uEnvironmentMappingEnabled" description="Enable environment mapping" type="Boolean" default="True"/>
+        <Property category="Shadow" formalName="Baked Shadow Map" name="uBakedShadowTexture" description="Baked shadow texture for the material" type="Texture" filter="linear" minfilter="linearMipmapLinear" clamp="repeat" usage="shadow" default="./maps/materials/shadow.png"/>
+        <Property category="Shadow" formalName="Shadow Mapping" name="uShadowMappingEnabled" description="Enable shadow mapping" type="Boolean" default="False"/>
+        <Property category="Material" formalName="Roughness" name="roughness" type="Float" min="0.0" max="1.0" default="0.3" description="Roughness of the material.\n0 = fully specular\n1 = fully diffuse"/>
+        <Property category="Material" formalName="Base color" name="base_color" type="Color" default="0.7 0.7 0.7" description="Color of the material"/>
+    </MetaData>
+\endcode
+
+The first option results in
+\image materials-category-dummy.png
+and the seconds one results in
+\image materials-category-several.png
 */