Clarify how custom materials can implement main function

Task-number: QT3DS-1701
Change-Id: Ie41cb000d99875f740f376b795cd95c568fd1e44
Reviewed-by: Mats Honkamaa <mats.honkamaa@qt.io>
Reviewed-by: Tomi Korpipää <tomi.korpipaa@qt.io>

1 files changed, 52 insertions, 0 deletions

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 d969cebc..fb6d4cba 100644
--- a/doc/src/07-file-formats/5-custom-material-reference.qdoc
+++ b/doc/src/07-file-formats/5-custom-material-reference.qdoc
@@ -45,6 +45,9 @@ The material system supports dielectric and transparent materials, point lights,
 area lights, ambient occlusion, shadowing, two-sided polygons,
 index-of-refraction and fragment cutoff(masking).
 
+It is also possible to write custom material without using the boilerplate code,
+in which case the main function must be implemented in the shader.
+
 \note The Qt 3D Studio 2.0 runtime does not support multiple render passes for
 custom materials.
 
@@ -462,6 +465,55 @@ void main()
 
 The only requirement is to leave the closing parenthesis out since the material system adds it.
 
+\section2 Simple Custom Material Example
+
+\badcode
+<Material name="simplecustom" version="1.0">
+    <MetaData >
+        <Property formalName="Red" name="red_weight" type="Float" default="1.0" min="0" max="1.0" category="Material"/>
+        <Property formalName="Green" name="green_weight" type="Float" default="1.0" min="0" max="1.0" category="Material"/>
+        <Property formalName="Blue" name="blue_weight" type="Float" default="1.0" min="0" max="1.0" category="Material"/>
+        <Property formalName="Base Color" name="basecolor" type="Texture" filter="linear" minfilter="linearMipmapLinear" clamp="repeat" category="Material"/>
+    </MetaData>
+    <Shaders type="GLSL" version="330">
+    <Shader>
+        <Shared></Shared>
+        <VertexShader>
+        </VertexShader>
+        <FragmentShader>
+#define UIC_ENABLE_UV0 1
+#define UIC_ENABLE_WORLD_POSITION 1
+#define UIC_ENABLE_TEXTAN 0
+#define UIC_ENABLE_BINORMAL 0
+
+#include "vertexFragmentBase.glsllib"
+#include "SSAOCustomMaterial.glsllib"
+#include "sampleLight.glsllib"
+#include "sampleProbe.glsllib"
+#include "sampleArea.glsllib"
+
+// Set shader output.
+out vec4 fragColor;
+
+    void main()
+    {
+        vec4 c = texture(basecolor, varTexCoord0.xy);
+        c.rgb *= vec3(red_weight, green_weight, blue_weight);
+        fragColor = c;
+
+        // No closing parenthesis because the generator adds it for us.
+        </FragmentShader>
+    </Shader>
+    </Shaders>
+    <Passes >
+        <ShaderKey value="7"/>
+        <LayerKey count="1"/>
+    <Pass >
+    </Pass>
+</Passes>
+</Material>
+\endcode
+
 \section1 ShaderKey
 
 ShaderKey-element is a magic number specifying how the material gets compiled. The value is