PrincipledMaterial QML Type

Lets you define a material for 3D items using the metal/roughness workflow. More...

Import Statement: import QtQuick3D .
Inherits:

Material

Properties

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 PrincipledMaterial is a PBR metal/roughness material that aims at being an easy to use material with a minimal set of parameters. In addition to having few parameters, all input values are strictly normalized between 0 and 1 and have sensible defaults, meaning even without changing any values, the material can be used to shader a model. For an introduction on how the different properties of the principled material affects how a model is shaded, see the Principled Material example.

Metal/Roughness workflow

The Principled material is what's known as a metal/roughness material, in essence that means the main characteristics of the material is controlled through the metallness, roughness, and the base color property.

Metalness

Real world materials are put into two main categories, metals and dielectrics (non-metals). In the Principled material, the category a material belongs to is decided by the metalness value. Setting the metalness value to 0, means the material is a dialectric, while everything above 0 is a considered to be a metal. In reality metals will have a metalness value of 1, but values between 0 and 1 are possible, and usually used for metals with reduced reflectance. For example, to render corrosion, or similar, on a material, the metalness of the material should be reduced to give the output properties more similar to a dielectric material. Since the metalness value affects the reflectance of the material it might be tempting to use the metalness to adjust glossiness, but consider what type of material you want to describe first. Increasing the metalness value to give a dielectric material a more polished look, will introduce properties that are not accurate for a dielectric material, so consider if it would be more appropriate to adjust, for example, the roughness value instead.

Roughness

The roughness of a material describes the condition of an object's surface. A low roughness value means the object has a smooth surface and therefore be more reflective then a material with a higher roughness value.

Base color

The base color of a metal/roughness material contains both the diffuse and the specular data, how much the base color is interpreted as one or the other is primarily dictated by the metalness value. For example, a material with a metalness value of 1, will have most of its base color interpreted as specular color, while the diffuse color would be a black tint. The opposite would happen for a material with a metalness value of 0. This is of course a bit simplified, but gives a rough idea how the base color and metalness value interacts. For those more familiar with a Specular/Glossiness workflow, there's a clear difference here which is worth noting, namely that the color data of the two materials are not directly compatible, since in a Specular/Glossiness material, the diffuse and specular color comes from separate inputs.

Property Documentation

alphaCutoff : real

The alphaCutoff property can be used to specify the cutoff value when using the Mask alphaMode. Fragments where the alpha value falls below the threshold will be rendered fully transparent (0.0 for all color channels). When the alpha value is equal or greater than the cutoff value, the color will not be affected in any way.

The default value is 0.5.

See also alphaMode.

alphaMode : enumeration

This property specifies how the alpha color value from baseColor and the alpha channel of a base color map are used.

Note: The alpha cutoff test only considers the base color alpha. opacity and Node::opacity are not taken into account there.

Note: When sampling a base color map, the effective alpha value is the sampled alpha multiplied by the baseColor alpha.

Constant Description
PrincipledMaterial.Default No test is applied, the effective alpha value is passed on as-is. Note that a baseColor alpha less than 1.0 does not automatically imply alpha blending, the object with the material may still be treated as opaque, if no other relevant properties (such as, an opacity less than 1, or the presence of an opacity map) trigger treating the object as semi-transparent. To ensure alpha blending happens, set Blend instead.
PrincipledMaterial.Blend No cutoff test is applied, but guarantees that alpha blending happens. The object with this material will therefore never be treated as opaque by the renderer.
PrincipledMaterial.Opaque The rendered object is fully opaque, if there is no other relevant properties (such as, an opacity less than 1, or the presence of an opacity map.) That is, all the alpha values in the vertex color, base color, and base color map are ignored.
PrincipledMaterial.Mask A test based on alphaCutoff is applied. If the effective alpha value falls below alphaCutoff, the fragment is changed to fully transparent. Otherwise the alpha is changed to 1, so that the fragment will become fully opaque. This mode implies Blend, meaning an object with a material having alphaMode set to Mask is rendered together with the semi-transparent objects, in back to front order, regardless of the cutoff test's result.

See also alphaCutoff.

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.

See also alphaMode.

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.

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.

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. All other shading properties except baseColor values, alpha values, and vertex colors will be ignored.

Constant Value
PrincipledMaterial.NoLighting
PrincipledMaterial.FragmentLighting

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.

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.

The range is [0.0, 1.0]. The default value is 0.

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.

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.

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. The range is [0.0, 1.0]. The default value is 0.

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).

The range is [0.0, 1.0]. The default value is 0.5.

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.

© The Qt Company Ltd
Licensed under the GNU Free Documentation License, Version 1.3.
https://doc.qt.io/qt-6.0/qml-qtquick3d-principledmaterial.html