diff options
Diffstat (limited to 'doc/src/07-file-formats/custom-materials-effects.qdoc')
| -rw-r--r-- | doc/src/07-file-formats/custom-materials-effects.qdoc | 116 |
1 files changed, 116 insertions, 0 deletions
diff --git a/doc/src/07-file-formats/custom-materials-effects.qdoc b/doc/src/07-file-formats/custom-materials-effects.qdoc index 7a1521cc..a083546d 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}. @@ -304,4 +311,113 @@ identifier-like name. <Shader name="tonemap"> \endcode +\section2 \c{<Passes>} +The \c{<Passes>} element can contain \c{<Pass>} elements. + +\section2 \c{<Pass>} +The \c{<Pass>} element contains different properties that are applied to the pass. More details +are provided in the \l{Effect Reference}. + +\section2 <Depth> +Custom materials have an additional Depth pass element not provided to effects. It determines +the depth function and masking used during this pass of the custom shader. + +The element attributes are: +\table +\header + \li attribute + \li values + \li description +\row + \li func + \li \list + \li \c never + \li \c less + \li \c less-than-or-equal + \li \c equal + \li \c not-equal + \li \c greater + \li \c greater-than-or-equal + \li \c always + \endlist + \li Specifies the depth function used. +\row + \li mask + \li bool + \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 + +\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. + +\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>"); +\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>", "sourcepath", "<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.diffuseTexture", "sourcepath", "../maps/myTexture.png"); +\endcode */ |