PrincipledMaterial QML Type

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.

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

See also alphaCutoff and blendMode.

This property defines the color that white lights turns into due to absorption when reaching the attenuation distance. The default value is Qt.White

This property defines the Density of the medium given as the average distance that light travels in the medium before interacting with a particle. The value is given in world space. The default value is +infinity.

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.

See also baseColorMap and alphaMode.

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

See also baseColor and alphaMode.

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

See also alphaMode and Qt Quick 3D Architecture.

This property defines the intensity of the clearcoat layer.

The default value is 0.0

This property defines the texture channel used to read the clearcoat amount value from clearcoatMap. The default value is Material.R.

This property defines a texture used to determine the intensity of the clearcoat layer. The value ofclearcoatAmount will be multiplied by the value read from this texture.

This property defines a texture used to determine the normal mapping applied to the clearcoat layer.

This property defines the roughness of the clearcoat layer. The default value is 0.0

This property defines the texture channel used to read the clearcoat roughness amount from clearcoatRoughnessMap. The default value is Material.G.

This property defines a texture used to determine the roughness of the clearcoat layer. The value ofclearcoatRoughnessAmount will be multiplied by the value read from this texture.

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.

This property sets a RGB Texture to be used to specify the intensity of the emissive color.

This property contains the factor used to modify the values from the heightMap texture. The value should be between 0.0 to 1.0. The default value is 0.0 which means that height displacement will be disabled, even if a height map set.

This property defines the texture channel used to read the height value from heightMap. The default value is Material.R.

This property defines a texture used to determine the height the texture will be displaced when rendered through the use of Parallax Mapping. Values are expected to be linear from 0.0 to 1.0, where 0.0 means no displacement and 1.0 means means maximum displacement.

This property defines the index of refraction of the material. The default value of 1.5 will be the ideal value for materials like plastics or glass but other materials like water, asphalt, sapphire, or diamond would require and adjusted value to look more realistic. For realistic materials the indexOfRefraction should usually be between 1.0 and 3.0

Some examples of common materials' index of refractions are:

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.

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.

This property defines the maximum number of samples used for performing Parallex Occlusion Mapping using the heightMap. The maxHeightMapSamples value is the number of samples of the heightMap are used when looking parallel to a surface. The default value is 32.

The actual number of samples used for each fragment will be between minHeightMapSamples and maxHeightMapSamples depending on the angle of the camera relative to the surface being rendered.

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.

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

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

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

This property defines the minimum number of samples used for performing Parallex Occlusion Mapping using the heightMap. The minHeightMapSamples value is the number of samples of the heightMap are used when looking directly at a surface (when the camera view is perpendicular to the fragment). The default value is 8.

The actual number of samples used for each fragment will be between minHeightMapSamples and maxHeightMapSamples depending on the angle of the camera relative to the surface being rendered.

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.

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

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

This property defines the texture channel used to read the occlusion value from occlusionMap. The default value is Material.R.

This property defines a texture used to determine how much 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 lighting and 1.0 means the effect of the lighting is left unchanged.

See also occlusionAmount.

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

This property defines the texture channel used to read the opacity value from opacityMap. The default value is Material.A.

This property defines a Texture used to control the opacity differently for different parts of the material.

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.

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.

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

This property defines a Texture to control the specular roughness of the material.

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

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

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.

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.

See also Texture::mappingMode.

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

This property defines the texture channel used to read the thickness amount from transmissionMap. The default value is Material.G.

This property defines the thickness of the volume beneath the surface. Unlike many other properties of PrincipledMaterial, the value in defined in thicknessFactor is a value from 0.0 to +infinity for thickness in the models coordinate space. A value of 0.0 means that the material is thin-walled. The default value is 0.0

This property defines a texture used to define the thickness of a material volume. The value of thicknessFactor will be multiplied by the value read from this texture.

This property defines the texture channel used to read the transmission percentage from transmissionMap. The default value is Material.R.

This property defines the percentage of light that is transmitted through the material's surface. The default value is 0.0

This property defines a texture used to determine percentage of light that is transmitted through the surface.. The value of transmissionFactor will be multiplied by the value read from this texture.

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. The default value is true.

This property was introduced in Qt 6.5.