- Qt 5.15
- Qt Quick 3D
- QML Types
- DefaultMaterial QML Type
- Qt Quick 3D | Commercial or GPLv3

# DefaultMaterial QML Type

Defines a Material generated depending on which properties are set. More...

Import Statement: | import QtQuick3D 1.15
Inherits: | Material

- List of all members, including inherited members

## Properties

- blendMode : enumeration
- bumpAmount : real
- bumpMap : Texture
- diffuseColor : color
- diffuseLightWrap : real
- diffuseMap : Texture
- emissiveColor : color
- emissiveFactor : real
- emissiveMap : Texture
- fresnelPower : real
- indexOfRefraction : real
- lighting : enumeration
- normalMap : Texture
- opacity : real
- opacityChannel : enumeration
- opacityMap : Texture
- roughnessChannel : enumeration
- roughnessMap : Texture
- specularAmount : real
- specularMap : Texture
- specularModel : enumeration
- specularReflectionMap : Texture
- specularRoughness : real
- specularTint : real
- 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 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.

## 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.
`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.
`DefaultMaterial.Overlay` | A mix of Multiply and Screen modes, producing a result with higher contrast.
`DefaultMaterial.ColorBurn` | Colors are blended by inverted division where the result also is inverted, producing a darker result. Darker than Multiply.
`DefaultMaterial.ColorDodge` | Colors are blended by inverted division, producing a lighter result. Lighter than Screen.

bumpAmount : real

This property controls the amount of simulated displacement for the bumpMap or normalMap. The default value is `0` disabling the bump effect. The range is [0, 1].

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. Use a displacementMap if this is required.

diffuseColor : color

This property determines the base color for the material. Set to black to 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.

emissiveColor : color

This property determines the color of self-illumination for this material.

emissiveFactor : real

This property determines the amount of self-illumination from the material. In a scene with black ambient lighting, a material with an emissive factor of 0 will appear black wherever the light does not shine on it. Turning the emissive factor to 1 will cause the material to appear in its diffuse color instead.

Note: When you want a material to not be affected by lighting, instead of using 100% emissiveFactor consider setting the lightingMode to /c DefaultMaterial.NoLighting for a performance benefit.

emissiveMap : Texture

This property sets a Texture to be used to set the emissive factor 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.

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.

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. Use a displacementMap if this is required.

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.

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.
`DefaultMaterial.KWard` | Specular lighting uses Ward lighting model.

specularReflectionMap : Texture

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.

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.

specularTint : real

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.