Commit 5a1a7a92 authored by Andy Nichols's avatar Andy Nichols
Browse files

Doc: Document properties of DefaultMaterial

parent 58e6d3be
Pipeline #4686 passed with stage
in 5 minutes and 7 seconds
......@@ -38,168 +38,317 @@ QT_BEGIN_NAMESPACE
/*!
\qmltype DefaultMaterial
\inqmlmodule QtQuick3D
\brief Lets you define material for the 3D item.
\brief Defines a Material generated depending on which properites are set.
Before a Model can be rendered in a scene, it must have at least one
material to define how the mesh is shaded. The DefaultMaterial is the
easiest way to define such a material. Even if you define a
DefaultMaterial with no properties set, a valid mesh will be rendered,
because the mesh defines some sensible defaults.
As you change the properties of the DefaultMaterial, behind the scenes
new shaders are generated, and the property values are bound. The
complexity of a shader depends on a combination of the properties that
are set on it, and the context of the scene itself.
*/
/*!
* \qmlproperty enumeration DefaultMaterial::lighting
*
* This property defines which lighting method is used when generating this
* material.
*
* The default value is \c DefaultMaterial.FragmentLighting
*
* When using \c DefaultMaterial.Fragment, diffuse and specular lighting is
* calculated for each rendered pixel. This produces better results than
* DefaultMaterial.VertexLighting but is slightly more expensive to compute.
* Certain effects (such as a Fresnel or bump map) require
* \c DefaultMaterial.Fragment lighting to work.
*
* When using \c DefaultMaterial.NoLighting no lighting is calculated. This
* mode is (predictably) very fast, and is quite effective when image maps are
* used that you do not need to be shaded by lighting.
*
* \list
* \li DefaultMaterial.NoLighting
* \li DefaultMaterial.VertexLighting
* \li DefaultMaterial.FragmentLighting
* \endlist
*/
/*!
* \qmlproperty enumeration DefaultMaterial::blendMode
*
* This property determines how the colors of the model rendered blends with
* those behind it.
*
* \list
* \li DefaultMaterial.Normal - Default blend mode. Opaque objects occlude
* objects behind them.
* \li DefaultMaterial.Screen - Colors are blended using an inverted multiply,
* producing a lighter result. This blend mode is order-independent; if you are
* using semi-opaque objects and experiencing 'popping' as faces or models sort
* differently, using Screen blending is one way to produce results without
* popping.
* \li DefaultMaterial.Multiply - Colors are blended using a multiply,
* producing a darker result. This blend mode is also order-independent.
* \li DefaultMaterial.Overlay - A mix of Multiply and Screen modes, producing
* a result with higher contrast.
* \li DefaultMaterial.ColorBurn - Colors are blended by inverted division where
* the result also is inverted, producing a darker result. Darker than Multiply.
* \li DefaultMaterial.ColorDodge - Colors are blended by inverted division,
* producing a lighter result. Lighter than Screen.
* \endlist
*
*/
/*!
* \qmlproperty color DefaultMaterial::diffuseColor
*
* This property determines the base color for the material. Set to black to
* create a purely-specular material (e.g. metals or mirrors).
*
*/
/*!
* \qmlproperty Texture DefaultMaterial::diffuseMap
*
* This property defines a Texture to apply to the material. Using Texture
* with transparency will also apply the alpha channel as an opacity map.
*
*/
/*!
* \qmlproperty Texture DefaultMaterial::diffuseMap2
*
* This property defines a second Texture to apply to the material. Using a
* Texture with transparency will also apply the alpha channel as an opacity
* map.
*
*/
/*!
* \qmlproperty Texture DefaultMaterial::diffuseMap3
*
* This property defines a thrid Texture to apply to the material. Using a
* Texture with transparency will also apply the alpha channel as an opacity
* map.
*
*/
/*!
* \qmlproperty real DefaultMaterial::emissivePower
*
* This property determines the amount of self-illumination from the material.
* In a scene with black ambient lighting a material with 0 emissive power will
* appear black wherever the light does not shine on it; turning the emissive
* power to 100 will cause the material to appear as its diffuse color instead.
*
* \note When you want a material to not be affected by lighting, instead of
* using 100% emissivePower consider setting the lightingMode to
* /c DefaultMaterial::NoLighting for a performance benefit.
*
*/
/*!
* \qmlproperty Texture DefaultMaterial::emissiveMap
*
* This property sets a Texture to be used to set the emissive power for
* different parts of the material. Using a grayscale image will not affect the
* color of the result, while using a color image will produce glowing regions
* with the color affected by the emissive map.
*
*/
/*!
* \qmlproperty color DefaultMaterial::emissiveColor
*
* This property determines the color of self-illumination for this material.
*
*/
/*!
* \qmlproperty Texture DefaultMaterial::specularReflectionMap
*
* This property sets a Texture used for specular highlights on the material.
* By default the Texture is applied using environmental mapping (not UV
* mapping): as you rotate the model the map will appear as though it is
* reflecting from the environment. Specular Reflection maps are an easy way to
* add a high-quality look with relatively low cost.
*
* \note Using a Light Probe in your SceneEnvironment for image-based lighting
* will automatically use that image as the specular reflection.
*
* \note Crisp images cause your material to look very glossy; the more you
* blur your image the softer your material will appear.
*
*/
/*!
* \qmlproperty Texture DefaultMaterial::specularMap
*
* The property defines a RGB Texture to modulate the amount and the color of
* specularity across the surface of the material. These values are multiplied
* by the specularAmount.
*
*/
/*!
* \qmlproperty enumeration DefaultMaterial::specularModel
*
* This property determines which functions are used to calculate specular
* highlights for lights in the scene.
*
* \list
* \li \c DefaultMaterial::Default
* \li \c DefaultMaterial::KGGX
* \li \c DefaultMaterial::KWard
* \endlist
*
*/
/*!
* \qmlproperty real DefaultMaterial::specularTint
*
* This property defines a color used to adjust the specular reflections.
* Use white for no effect
*
*/
/*!
* \qmlproperty real DefaultMaterial::indexOfRefraction
*
* This property controls what angles of reflections are affected by the
* fresnelPower.
*
*/
/*!
* \qmlproperty real DefaultMaterial::fresnelPower
*
* This property decreases head-on reflections (looking directly at the
* surface) while maintaining reflections seen at grazing angles.
*
*/
/*!
* \qmlproperty real DefaultMaterial::specularAmount
*
* This property controls the strength of specularity (highlights and
* reflections).
*
* \note This property does not affect the
* DefaultMaterial::specularReflectionMap, but does affect the amount of
* reflections from a scenes SceneEnvironment::lightProbe.
*
* \note Unless your mesh is high resolution, you may need to use
* DefaultMaterial::FragmentLighting to get good specular highlights from scene
* lights.
*
*/
/*!
* \qmlproperty real DefaultMaterial::specularRoughness
*
* This property controls the size of the specular highlight generated from
* lights, and the clarity of reflections in general. Larger values increase
* the roughness, softening specular highlights and blurring reflections.
*
*/
/*!
* \qmlproperty Texture DefaultMaterial::roughnessMap
*
* This property defines a Texture to control the specular roughness of the
* material.
*
*/
/*!
* \qmlproperty real DefaultMaterial::opacity
*
* This property drops the opacity of just this matrial, separate from the
* model.
*
*/
/*!
* \qmlproperty Texture DefaultMaterial::opacityMap
*
* This property defines a Texture used to control the opacity differently for
* different parts of the material.
*
* \note This must be an image format with transparency for the opacity to be
* applied.
*
*/
/*!
* \qmlproperty Texture DefaultMaterial::bumpMap
*
* This property defines a a grayscale Texture to simulate fine geometry
* displacement across the surface of the material. Brighter pixels indicate
* raised regions. The amount of the effect is controlled by the
* DefaultMaterial::bumpAmount property.
*
* \note bump maps will not affect the silhouette of a model. Use a
* displacementMap if this is required.
*
*/
/*!
* \qmlproperty real DefaultMaterial::bumpAmount
*
* This property controls the amount of simulated displacement for the
* DefaultMaterial::bumpMap or DefaultMaterial::normalMap.
*
*/
/*!
* \qmlproperty Texture DefaultMaterial::normalMap
*
* This property defines an RGB image used to simulate fine geometry
* displacement across the surface of the material. The RGB channels indicate
* XYZ normal deviations. The amount of the effect is controlled by the
* DefaultMaterial::bumpAmount property.
*
* \note Normal maps will not affect the silhouette of a model. Use a
* DefaultMaterial::displacementMap if this is required.
*
*/
/*!
* \qmlproperty Texture DefaultMaterial::translucencyMap
*
* This property defines a grayscale Texture controlling how much light can
* pass through the material from behind.
*
*/
/*!
* \qmlproperty real DefaultMaterial::translucentFalloff
*
* The property defines the amount of falloff for the translucency based on the
* angle of the normals of the object to the light source.
*
*/
/*!
* \qmlproperty real DefaultMaterial::diffuseLightWrap
*
* The property determines the amount of light wrap for the translucency map.
* A value of 0 will not wrap the light at all while a value of 1 will wrap
* the light all around the object.
*
*/
/*!
* \qmlproperty real DefaultMaterial::vertexColors
* \qmlproperty bool DefaultMaterial::vertexColors
*
* When this property is enabled the material will Use vertex colors from the
* mesh. These will be multiplied by any other colors specified for the
* material.
*
*/
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment