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

# PrincipledMaterial QML Type

Lets you define a material for 3D items. More...

Import Statement: | import QtQuick3D 1.15
Inherits: | Material

- List of all members, including inherited members

## Properties

- alphaCutoff : real
- alphaMode : enumeration
- baseColor : color
- baseColorMap : Texture
- blendMode : enumeration
- emissiveColor : color
- emissiveMap : Texture
- indexOfRefraction : real
- lighting : enumeration
- metalness : real
- metalnessChannel : enumeration
- metalnessMap : Texture
- normalMap : Texture
- normalStrength : real
- occlusionAmount : real
- occlusionChannel : enumeration
- occlusionMap : Texture
- opacity : real
- opacityChannel : enumeration
- opacityMap : Texture
- roughness : real
- roughnessChannel : enumeration
- roughnessMap : Texture
- specularAmount : real
- specularMap : Texture
- specularReflectionMap : Texture
- specularTint : real

## 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 PrincipledMaterial aims to be easy to use and with as few parameters as possible. In addition to having few parameters, all input values are strictly normalized between 0 and 1. Even if you define a PrincipledMaterial with no properties set, a valid mesh will be rendered, because the mesh defines some sensible defaults.

As you change the properties of the PrincipledMaterial, 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

alphaCutoff : real

The alphaCutoff property can be used to specify the cutoff value when using the Mask alphaMode. Alpha values below the threshold will be rendered fully transparent, everything else will be fully opaque. The default value is 0.5

See also alphaMode.

alphaMode : enumeration

This property sets the mode for how the alpha channel of material color is used.

Constant | Description
--- | ---
`PrincipledMaterial.Opaque` | The alpha channel is ignored and the output is rendered fully opaque. This is the default.
`PrincipledMaterial.Mask` | The output is either fully transparent of fully opaque depending on the alpha value and the specified alphaCutoff value.
`PrincipledMaterial.Blend` | The output is blended with the background.

Note: These modes only consider the alpha channel of the material's color or color map. The general opacity of the material does therefore not affect how the `alphaMode` or `alphaCutoff` is interpreted.

baseColor : color

This property sets the base color for the material. Depending on the type of material specified (metal or dielectric) the diffuse and specular channels will be set appropriately. For example, a dielectric material will have a diffuse color equal to the base color, while it's specular color, depending on the specular amount, will have a bright specular color. For metals the diffuse and specular channels will be mixed from the base color and have a dark diffuse channel and a specular channel close to the base color.

baseColorMap : Texture

This property defines the texture used to set the base color of the material.

See also baseColor.

blendMode : enumeration

This property determines how the colors of the model rendered blends with those behind it.

Constant | Description
--- | ---
`PrincipledMaterial.SourceOver` | Default blend mode. Opaque objects occlude objects behind them.
`PrincipledMaterial.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.
`PrincipledMaterial.Multiply` | Colors are blended using a multiply, producing a darker result. This blend mode is also order-independent.
`PrincipledMaterial.Overlay` | A mix of Multiply and Screen modes, producing a result with higher contrast.
`PrincipledMaterial.ColorBurn` | Colors are blended by inverted division where the result also is inverted, producing a darker result. Darker than Multiply.
`PrincipledMaterial.ColorDodge` | Colors are blended by inverted division, producing a lighter result. Lighter than Screen.

emissiveColor : color

This property determines the color of self-illumination for this material. If an emissive map is set, this property is used as a factor for the RGB channels of the texture.

Note: In a scene with black ambient lighting a material with a 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 as 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 `PrincipledMaterial.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.

indexOfRefraction : real

This property controls how fast light travels through the material.

lighting : enumeration

This property defines which lighting method is used when generating this material.

The default value is `PrincipledMaterial.FragmentLighting`

When using `PrincipledMaterial.FragmentLighting`, diffuse and specular lighting is calculated for each rendered pixel. Certain effects (such as a Fresnel or normal map) require `PrincipledMaterial.FragmentLighting` to work.

When using `PrincipledMaterial.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.

Constant | Value
--- | ---
`PrincipledMaterial.NoLighting`
`PrincipledMaterial.FragmentLighting`

metalness : real

The metalness property defines the metalness of the the material. The value is normalized, where 0.0 means the material is a dielectric (non-metallic) material and a value of 1.0 means the material is a metal.

Note: In principle, materials are either dielectrics with a metalness of 0, or metals with a metalness of 1. Metalness values between 0 and 1 are still allowed and will give a material that is a blend between the different models.

metalnessChannel : enumeration

This property defines the texture channel used to read the metalness value from metalnessMap. The default value is `Material.B`.

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.

metalnessMap : Texture

This property sets a Texture to be used to set the metalness amount for the different parts of the material.

normalMap : Texture

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.

Note: Normal maps will not affect the silhouette of a model.

normalStrength : real

This property controls the amount of simulated displacement for the normalMap.

occlusionAmount : real

This property contains the factor used to modify the values from the occlusionMap texture. The value should be between 0.0 to 1.0. The default is 1.0

occlusionChannel : enumeration

This property defines the texture channel used to read the occlusion value from occlusionMap. 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.

occlusionMap : Texture

This property defines a texture used to determine how much indirect light the different areas of the material should receive. Values are expected to be linear from 0.0 to 1.0, where 0.0 means no indirect lighting and 1.0 means the effect of the indirect lighting is left unchanged.

See also occlusionAmount.

opacity : real

This property drops the opacity of just this material, separate from the model.

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.

roughness : 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.

roughnessChannel : enumeration

This property defines the texture channel used to read the roughness value from roughnessMap. The default value is `Material.G`.

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.

specularAmount : real

This property controls the strength of specularity (highlights and reflections).

Note: For non-dielectrics (metals) this property has no effect.

Note: This property does not affect the 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 `PrincipledMaterial.FragmentLighting` to get good specular highlights from scene lights.

specularMap : Texture

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.

Note: The specular map will be ignored unless the material is dielectric.

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.

specularTint : real

This property defines how much of the base color contributes to the specular reflections.

Note: This property does only apply to dielectric materials.