DefaultMaterial QML Type
Lets you define a material for 3D items using the specular/glossiness workflow. More...
| Import Statement: | import QtQuick3D |
| Inherits: |
Properties
- blendMode : enumeration
- bumpAmount : real
- bumpMap : Texture
- diffuseColor : color
- diffuseLightWrap : real
- diffuseMap : Texture
- emissiveFactor : vector3d
- emissiveMap : Texture
- fresnelPower : real
- indexOfRefraction : real
- lighting : enumeration
- lineWidth : real
- normalMap : Texture
- opacity : real
- opacityChannel : enumeration
- opacityMap : Texture
- pointSize : real
- roughnessChannel : enumeration
- roughnessMap : Texture
- specularAmount : real
- specularMap : Texture
- specularModel : enumeration
- specularReflectionMap : Texture
- specularRoughness : real
- specularTint : color
- translucencyChannel : enumeration
- translucencyMap : Texture
- translucentFalloff : real
- vertexColorsEnabled : bool
Detailed Description
Before a Model can be rendered in a scene, it must have at least one material attached to it that describes how the mesh should be shaded. The DefaultMaterial is an easy to use material that lets you describe your material using a specular/glossiness type workflow. The material has sensible default and can be used to shade a model without changing any properties.
Specular/Glossiness workflow
The Default material provides a way to create materials using a specular/glossiness type workflow. The main properties of the material are controlled through the specular, roughness, and the diffuse color property.
Specular
The specular reflectivity describes the specular amount and color of an object's surface. For reflective materials the main color contribution, comes from this property.
Glossiness (Roughness)
The glossiness of a surface depends on how smooth or irregular the surface is. A smooth surface will have a more intense light reflection then a rough surface, where the light reflection will be more spread out. In the Default material the material's glossiness is controlled through the roughness property.
Diffuse color
The diffuse color property describes the basic color of the material, and unlike the PrincipledMaterial's base color, the diffuse color does not contain any information about the material reflectance. However, for reflective surfaces the diffuse color should be set to a black tint, as that will allow for the specular color to contribute.
Property Documentation
blendMode : enumeration |
This property determines how the colors of the model rendered blend with those behind it.
| Constant | Description |
|---|---|
DefaultMaterial.SourceOver | Default blend mode. Opaque objects occlude objects behind them. This default mode does not guarantee alpha blending in the rendering pipeline on its own for models that use this material, but rather makes the decision dependent on a number of factors: if the object's and material's total opacity is 1.0 and there are no texture maps in the material with semi-transparent pixels in them, then the model is treated as opaque, meaning it is rendered with depth testing and depth write enabled, together with other opaque objects, with blending disabled. Otherwise the model is treated as semi-transparent, and is rendered after the opaque objects, together with other semi-transparent objects in a back-to-front order based on their center's distance from the camera, with alpha blending enabled. |
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. |
DefaultMaterial.Multiply | Colors are blended using a multiply, producing a darker result. This blend mode is also order-independent. |
See also Qt Quick 3D Architecture.
bumpAmount : real |
bumpMap : Texture |
This property defines 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 bumpAmount property.
Note: bump maps will not affect the silhouette of a model.
diffuseColor : color |
This property determines the diffuse color (albedo) for the material. Setting the diffuse color to a black tint will create a purely-specular material (e.g. metals or mirrors).
diffuseLightWrap : real |
This 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.
diffuseMap : Texture |
This property defines a Texture to apply to the material. Using Texture with transparency will also apply the alpha channel as an opacity map.
emissiveFactor : vector3d |
This property determines the color of self-illumination for this material. If an emissive map is set, the x, y, and z components are used as factors (multipliers) for the R, G and B channels of the texture, respectively. The default value is (0, 0, 0) and it means no emissive contribution at all.
Note: Setting the lightingMode to DefaultMaterial.NoLighting means emissive Factor does not have an effect on the scene.
emissiveMap : Texture |
This property sets a RGB Texture to be used to specify the intensity of the emissive color.
See also emissiveFactor.
fresnelPower : real |
This property decreases head-on reflections (looking directly at the surface) while maintaining reflections seen at grazing angles. The default value is 0 disabling the fresnel effect.
indexOfRefraction : real |
This property controls what angles of reflections are affected by the fresnelPower. The default is 1.45. The value must be greater or equal to 1.0.
Note: No known material in the world have ior much greater than 3.0.
lighting : enumeration |
This property defines which lighting method is used when generating this material.
The default value is DefaultMaterial.FragmentLighting
When using DefaultMaterial.FragmentLighting, diffuse and specular lighting are calculated for each rendered pixel. Certain effects (such as a Fresnel or bump map) require DefaultMaterial.FragmentLighting to work.
When using DefaultMaterial.NoLighting no lighting is calculated. This mode is (predictably) very fast, and quite effective when image maps are used that do not need to be shaded by lighting.
| Constant | Description |
|---|---|
DefaultMaterial.NoLighting | No lighting is calculated. |
DefaultMaterial.FragmentLighting | Per-fragment lighting is calculated. |
lineWidth : real |
This property determines the width of the lines rendered, when the geometry is using a primitive type of lines or line strips. The default value is 1.0. This property is not relevant when rendering other types of geometry, such as, triangle meshes.
Warning: Line widths other than 1 may not be suported at run time, depending on the underlying graphics API. When that is the case, the request to change the width is ignored. For example, none of the following can be expected to support wide lines: Direct3D, Metal, OpenGL with core profile contexts.
Note: Unlike most other material properties, the line width is under the hood baked in to a graphics pipeline object, similarly to blendMode. Therefore, a different value leads to having to create a new pipeline object, which over time can become costly (performance and resource usage) if the property is frequently changed to many different values. For example, animating this property is possible, but should be avoided.
normalMap : Texture |
This property defines a 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 bumpAmount property.
Note: Normal maps will not affect the silhouette of a model.
opacity : real |
This property drops the opacity of just this material, separate from the model. The default is 1.0. The range is [0.0, 1.0].
opacityChannel : enumeration |
This property defines the texture channel used to read the opacity value from opacityMap. The default value is Material.A.
| Constant | Description |
|---|---|
Material.R | Read value from texture R channel. |
Material.G | Read value from texture G channel. |
Material.B | Read value from texture B channel. |
Material.A | Read value from texture A channel. |
opacityMap : Texture |
This property defines a Texture used to control the opacity differently for different parts of the material.
pointSize : real |
This property determines the size of the points rendered, when the geometry is using a primitive type of points. The default value is 1.0. This property is not relevant when rendering other types of geometry, such as, triangle meshes.
Warning: Point sizes other than 1 may not be supported at run time, depending on the underyling graphics API. For example, setting a size other than 1 has no effect with Direct 3D.
roughnessChannel : enumeration |
This property defines the texture channel used to read the roughness value from roughnessMap. The default value is Material.R.
| Constant | Description |
|---|---|
Material.R | Read value from texture R channel. |
Material.G | Read value from texture G channel. |
Material.B | Read value from texture B channel. |
Material.A | Read value from texture A channel. |
roughnessMap : Texture |
This property defines a Texture to control the specular roughness of the material. If the texture contains multiple channels(RGBA), then the correct channel can be set using the roughnessChannel property.
specularAmount : real |
This property controls the strength of specularity (highlights and reflections). The default value is 0 disabling the specularity. The range is [0.0, 1.0].
Note: This property does not affect the specularReflectionMap, but does affect the amount of reflections from a scene's SceneEnvironment::lightProbe.
Note: Unless your mesh is high resolution, you may need to use DefaultMaterial.FragmentLighting to get good specular highlights from scene lights.
specularMap : Texture |
This 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.
specularModel : enumeration |
This property determines which functions are used to calculate specular highlights for lights in the scene.
| Constant | Description |
|---|---|
DefaultMaterial.Default | Specular lighting uses default lighting model. |
DefaultMaterial.KGGX | Specular lighting uses GGX lighting model. |
specularReflectionMap : Texture |
This property sets a Texture used for specular highlights on the material.
This is typically used to perform environment mapping: as the model is rotated, the map will appear as though it is reflecting from the environment. For this to work as expected, the Texture's mappingMode needs to be set to Texture.Environment. Specular reflection maps are an easy way to add a high-quality look with a relatively low cost.
Note: Associating a light probe with the SceneEnvironment, and thus relying on image-based lighting, can achieve similar environmental reflection effects. Light probes are however a conceptually different, and when it comes to performance, potentially more expensive solution. Each approaches have their own specific uses, and the one to use needs to be decided on a case by case basis. When it comes to the Texture set to the property, specularReflectionMap has an advantage, because it presents no limitations and supports all types of textures, including ones that source their data from a Qt Quick sub-scene via sourceItem.
Note: Crisp images cause your material to look very glossy; the more you blur your image the softer your material will appear.
See also Texture::mappingMode.
specularRoughness : real |
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. The range is [0.0, 1.0]. The default value is 0.
specularTint : color |
This property defines a color used to adjust the specular reflections. Use white for no effect
translucencyChannel : enumeration |
This property defines the texture channel used to read the translucency value from translucencyMap. The default value is Material.A.
| Constant | Description |
|---|---|
Material.R | Read value from texture R channel. |
Material.G | Read value from texture G channel. |
Material.B | Read value from texture B channel. |
Material.A | Read value from texture A channel. |
translucencyMap : Texture |
This property defines a grayscale Texture controlling how much light can pass through the material from behind.
translucentFalloff : real |
This property defines the amount of falloff for the translucency based on the angle of the normals of the object to the light source.
vertexColorsEnabled : bool |
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.
© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.
