SpecularGlossyMaterial QML Type
Lets you define a material for 3D items using the specular/glossiness workflow. More...
| Import Statement: | import QtQuick3D |
| Inherits: |
Properties
- albedoColor : color
- albedoMap : Texture
- alphaCutoff : real
- alphaMode : enumeration
- attenuationColor : color
- attenuationDistance : float
- blendMode : enumeration
- clearcoatAmount : float
- clearcoatChannel : enumeration
- clearcoatMap : Texture
- clearcoatNormalMap : Texture
- clearcoatRoughnessAmount : float
- clearcoatRoughnessChannel : enumeration
- clearcoatRoughnessMap : Texture
- emissiveFactor : vector3d
- emissiveMap : Texture
- glossiness : real
- glossinessChannel : enumeration
- glossinessMap : Texture
- heightAmount : real
- heightChannel : enumeration
- heightMap : Texture
- lighting : enumeration
- lineWidth : real
- maxHeightMapSamples : int
- minHeightMapSamples : int
- normalMap : Texture
- normalStrength : real
- occlusionAmount : real
- occlusionChannel : enumeration
- occlusionMap : Texture
- opacity : real
- opacityChannel : enumeration
- opacityMap : Texture
- pointSize : real
- specularColor : color
- specularMap : Texture
- thicknessChannel : enumeration
- thicknessFactor : float
- thicknessMap : Texture
- transmissionChannel : enumeration
- transmissionFactor : float
- transmissionMap : Texture
- 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 SpecularGlossyMaterial is a PBR specular/glossiness 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 SpecularGlossyMaterial affects how a model is shaded, see the Principled Material example which provides a mode for using the Specular/Glossy workflow.
Alternatively to use the metallic/roughness workflow instead use PrincipledMaterial.
Specular/Glossiness workflow
The SpecularGlossyMaterial provides a way to create materials using a specular/glossiness type workflow. The main properties of the material is controlled through the specular, glossiness, and albedo properties.
Specular
The specularColor property describes the specular amount and color of an object's surface. For reflective materials the main color contribution, comes from this property.
Glossiness
The glossiness of a material describes the condition of an object's surface. A high glossiness value means the object has a smooth surface and therefore be more reflective then a material with a lower glossiness value.
Albedo
The albedoColor property describes the diffuse color of the material, and unlike the PrincipledMaterial's base color, the albedo does not contain any information about the material reflectance. That means that for reflective surfaces the albedo's color value should be set to a black tint, as that will allow for the specular color to contribute.
Property Documentation
albedoColor : color |
albedoMap : Texture |
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 albedoColor and the alpha channel of a albedo map are used.
Note: The alpha cutoff test only considers the albedo color alpha. opacity and Node::opacity are not taken into account there.
Note: When sampling an albedo color map, the effective alpha value is the sampled alpha multiplied by the albedoColor alpha.
| Constant | Description |
|---|---|
SpecularGlossyMaterial.Default | No test is applied, the effective alpha value is passed on as-is. Note that a albedoColor or albedoMap 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, the presence of an opacity map, or a non-default blendMode value) trigger treating the object as semi-transparent. To ensure alpha blending happens regardless of any other object or material property, set Blend instead. |
SpecularGlossyMaterial.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. |
SpecularGlossyMaterial.Opaque | No cutoff test is applied and the rendered object is assumed to be fully opaque, meaning the alpha values in the vertex color, albedo color, and albedo color map are ignored and a value of 1.0 is substituted instead. This mode does not guarantee alpha blending does not happen. If relevant properties (such as, an opacity less than 1, an opacity map, or a non-default blendMode) say so, then the object will still be treated as semi-transparent by the rendering pipeline, just like with the Default alphaMode. |
SpecularGlossyMaterial.Mask | A test based on alphaCutoff is applied. If the effective alpha value falls below alphaCutoff, the fragment is changed to fully transparent and is discarded (with all implications of discarding: the depth buffer is not written for that fragment). Otherwise the alpha is changed to 1.0, so that the fragment will become fully opaque. When it comes to alpha blending, the behavior of this mode is identical to Opaque, regardless of the cutoff test's result. This means that the glTF 2 spec's alpha coverage Implementation Notes are fulfilled. Objects with alpha cutoff tests can also cast shadows since they behave like opaque objects by default, unless the relevant properties (such as, an opacity less than 1, an opacity map, or a non-default blendMode) imply otherwise (in which case casting shadows will not be possible). |
See also alphaCutoff and blendMode.
attenuationColor : color |
This property defines the color that white lights turns into due to absorption when reaching the attenuation distance. The default value is Qt.White
attenuationDistance : float |
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.
blendMode : enumeration |
This property determines how the colors of the model rendered blends with those behind it.
| Constant | Description |
|---|---|
SpecularGlossyMaterial.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, there is no opacity map in the material, and alphaMode is not set to a value that enforces alpha blending, 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. |
SpecularGlossyMaterial.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. |
SpecularGlossyMaterial.Multiply | Colors are blended using a multiply, producing a darker result. This blend mode is also order-independent. |
See also alphaMode and Qt Quick 3D Architecture.
clearcoatAmount : float |
This property defines the intensity of the clearcoat layer.
The default value is 0.0
clearcoatChannel : enumeration |
This property defines the texture channel used to read the clearcoat amount value from clearcoatMap. 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. |
clearcoatMap : Texture |
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.
clearcoatNormalMap : Texture |
This property defines a texture used to determine the normal mapping applied to the clearcoat layer.
clearcoatRoughnessAmount : float |
This property defines the roughness of the clearcoat layer. The default value is 0.0
clearcoatRoughnessChannel : enumeration |
This property defines the texture channel used to read the clearcoat roughness amount from clearcoatRoughnessMap. 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. |
clearcoatRoughnessMap : Texture |
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.
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.
glossiness : real |
This property controls the size of the specular highlight generated from lights, and the clarity of reflections in general. Smaller values increase the roughness, softening specular highlights and blurring reflections. The range is [0.0, 1.0]. The default value is 1.0.
glossinessChannel : enumeration |
This property defines the texture channel used to read the glossiness value from glossinessMap. 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. |
glossinessMap : Texture |
This property defines a Texture to control the glossiness of the material.
heightAmount : real |
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.
heightChannel : enumeration |
This property defines the texture channel used to read the height value from heightMap. 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. |
heightMap : Texture |
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.
lighting : enumeration |
This property defines which lighting method is used when generating this material.
The default value is SpecularGlossyMaterial.FragmentLighting
| Constant | Description |
|---|---|
SpecularGlossyMaterial.FragmentLighting | Diffuse and specular lighting is calculated for each rendered pixel. Certain effects (such as a Fresnel or normal map) require SpecularGlossyMaterial.FragmentLighting to work. |
SpecularGlossyMaterial.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 albedo values, alpha values, and vertex colors will be ignored. |
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.
maxHeightMapSamples : int |
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.
Note: This value should only be adjusted to fine tune materials using a heightMap in the case undesired artifacts are present.
minHeightMapSamples : int |
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.
Note: This value should only be adjusted to fine tune materials using a heightMap in the case undesired artifacts are present.
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.
specularColor : color |
This property defines the specular RGB color. If an alpha value is provided it will be ignored.
The default value is Qt.White
specularMap : Texture |
This property sets a Texture to be used to set the specular color for the different parts of the material. Only the RGB channels are used.
thicknessChannel : enumeration |
This property defines the texture channel used to read the thickness amount from transmissionMap. 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. |
thicknessFactor : float |
This property defines the thickness of the volume beneath the surface. Unlike many other properties of SpecularGlossyMaterial, 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
thicknessMap : Texture |
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.
transmissionChannel : enumeration |
This property defines the texture channel used to read the transmission percentage from transmissionMap. 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. |
transmissionFactor : float |
This property defines the percentage of light that is transmitted through the material's surface. The default value is 0.0
transmissionMap : Texture |
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.
[since 6.5] 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. The default value is true.
This property was introduced in Qt 6.5.
© 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.
