IMaterial

Description

interface Tinman.Engine.Models.IMaterial

Derived from: IEquatable<IMaterial>
IConfigurable
Extended by: Material ^sealed

Defines a visual material of a 3D model part (see IModelPart.Material).

Materials use the metallic-roughness or the specular-glossiness workflow for Physically-Based Rendering (PBR) with optional light transmission and refraction, as defined by the glTF 2.0 specification:

Metallic-Roughness Material
https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#materials
Metallic-Roughness-Specular Material
https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_materials_specular
Specular-Glossiness Material
https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Archived/KHR_materials_pbrSpecularGlossiness
Emissive Strength
https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_materials_emissive_strength
Light Transmission
https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Khronos/KHR_materials_transmission
Index of Refraction
https://github.com/KhronosGroup/glTF/tree/main/extensions/2.0/Khronos/KHR_materials_ior

The IMaterial interface follows these specifications and allows to specify PBR material properties for either the metallic-roughness workflow or the specular-glossiness workflow:

Metallic-roughness:
The base color (see BaseColor) represents both the non-metallic albedo/diffuse color and the metallic specular/reflection color, where the metalness (see Metalness) distinguishes between metallic and non-metallic parts. The reflectivity (see Reflectivity) represents the non-metallic specular/reflection color, which modulates the pure-white diffuse reflectivity that is defined by the refraction index (see Refraction), for example 4% for an index of 1.5.
Specular-glossiness workflow:
The base color (see BaseColor) only represents the albedo/diffuse color and explicit metalness is not used (see Metalness). The reflectivity (see Reflectivity) represents the metallic specular/reflection color and intensity, where the latter implicitly defines metalness.

The individual material components are defined by these material properties:

Base color and transparency: BaseColor, Opacity, ModelPartFlags.VertexColorIsBaseColor, ModelPartFlags.VertexAlphaIsOcclusion
```
glTF / pbrMetallicRoughness / baseColorFactor.rgba
glTF / pbrMetallicRoughness / baseColorTexture.rgba
glTF / KHR_materials_pbrSpecularGlossiness / diffuseFactor.rgba
glTF / KHR_materials_pbrSpecularGlossiness / diffuseTexture.rgba
glTF / alphaMode
```
Depending on ModelPartFlags.Transparent, either RenderStatePreset.AlphaBlending or RenderStatePreset.AlphaCoverage is used. With ModelPartFlags.Opaque, all transparency information will be ignored, resulting in fully opaque rendering.
Displacement of surface: Displacement
Texture samples in the range [0..1] are mapped to model-space offset vectors of length [-Value..+Value], along the surface normal vector.

Emissive color: Emissive

glTF / emissiveFactor.rgb
glTF / emissiveTexture.rgb
glTF / KHR_materials_emissive_strength / emissiveStrength

Glossiness / roughness of surface: Glossiness, Roughness

glTF / pbrMetallicRoughness / roughnessFactor
glTF / pbrMetallicRoughness / metallicRoughnessTexture.g
glTF / KHR_materials_pbrSpecularGlossiness / glossinessFactor
glTF / KHR_materials_pbrSpecularGlossiness / specularGlossinessTexture.a

Line thickness: LineThickness

Metalness of surface: Metalness

glTF / pbrMetallicRoughness / metallicFactor
glTF / pbrMetallicRoughness / metallicRoughnessTexture.b

Normal vectors of surface: Normal
```
glTF / normalTexture / scale
glTF / normalTexture / index.rgb
```
The red, green and blue intensities in the range [0..1] are mapped to the range [-1..+1] along the X, Y and Z-axis, where the X+ axis is the tangent direction (positive texture U-axis), Y+ is the bitangent direction (positive texture V-axis) and Z+ is direction of the surface normal vector.
Occlusion of ambient light: Occlusion, ModelPartFlags.VertexAlphaIsOcclusion
```
glTF / occlusionTexture / strength
glTF / occlusionTexture / index.r
```

Reflectivity of surface: Reflectivity

glTF / KHR_materials_specular / specularColorFactor.rgb
glTF / KHR_materials_specular / specularColorTexture.rgb
glTF / KHR_materials_pbrSpecularGlossiness / specularFactor.rgb
glTF / KHR_materials_pbrSpecularGlossiness / specularGlossinessTexture.rgb

Please note that the two PBR workflows interpret reflectivity in different ways.

Refraction index: Refraction
```
glTF / KHR_materials_ior / ior
```
The index of refraction influences the pure-white diffuse reflection intensity that is used by the metallic-roughness PBR workflow and the blurriness of transmitted light. For the specular-glossiness PBR workflow, the index of refraction should be taken into account when specifying the reflection color and intensity, for example by using the Material.ReflectivityDefaultColor method.
Specularity of surface: Specularity
```
glTF / KHR_materials_specular / specularFactor
glTF / KHR_materials_specular / specularTexture.a
```
The specularity controls the overall strength of the specular reflections that are defined by the other material properties.
Translucency of surface: Translucency
For a double-sided material, the same diffuse lighting calculations as for the base color are performed, using the translucency color and flipped normal vector instead.
Transmission of light: Transmission
```
glTF / KHR_materials_transmission / transmissionFactor
glTF / KHR_materials_transmission / transmissionTexture.r
```
The transmission controls how much light passes through the material, instead of being reflected diffusely.

The same IModelTexture object may be specified for multiple material properties, which allows composite textures to be used for more than one material property at a time. When doing so, the color channel usage as well as the behaviour regarding sRGB must be taken into account:

BaseColor : sRGB + A
Displacement : R | G | B | A
Emissive : sRGB
Glossiness : R | G | B | A
Metalness : R | G | B | A
Normal : RGB
Occlusion : * | G | B | A
Opacity : R | G | B | A
Reflectivity : sRGB
Roughness : R | G | B | A
Specularity : R | G | B | A
Translucency : sRGB
Transmission : R | G | B | A

For the single-channel material properties, the default texture channel (red) may be changed via IMaterialPartBase.Channel.

Public / Methods

Copy

public method Copy → ()

returns → Material: The mutable copy.

Creates a mutable copy of this material object.

Modifying the returned Material will not affect this material object.

See also: IMaterial.Mutable

Simplify

[Pure]
public method Simplify → (1)

textures ^opt : IMap<IResourceHandle, IResourceHandle> = null: Optional map to use for replacing different IModelTexture objects that are equivalent with the first occurrence.
returns → IMaterial: The simplified material. Will be this iff no information has been discarded.

Simplifies this material by discarding redundant information.

Redundant information is discarded according to these rules:

If Displacement.IMaterialPart.Value is almost equal to 0:
clear Displacement.
If Emissive.IMaterialPart.Value is equal to ColorF.Black:
clear Emissive.
If Glossiness.IMaterialPart.Value is almost equal to 0:
clear Glossiness.
If Metalness.IMaterialPart.Value is negative:
clear Metalness and Roughness.
If Metalness.IMaterialPart.Value is almost equal to 0:
clear Metalness to 0.
If Normal.IMaterialPart.Value is almost equal to 0:
clear Normal to 0.
If Occlusion.IMaterialPart.Value is almost equal to 0:
clear Occlusion to 0.
If Reflectivity.IMaterialPart.Value is equal to ColorF.Black:
clear Reflectivity to ColorF.Black.
If Roughness.IMaterialPart.Value is almost equal to 0:
clear Roughness to 0.
If Specularity.IMaterialPart.Value is almost equal to 0:
clear Specularity to 0.
If Translucency.IMaterialPart.Value is equal to ColorF.Black:
clear Translucency.
If Transmission.IMaterialPart.Value is equal to 0:
clear Transmission to 0.

See also: MaterialPartBase.Clear
Maths.Similar¹

Public / Attributes

BaseColor

[Constant]
public attribute BaseColor → (get)

value : IMaterialPart<ColorF>: [not-null]
The material part.

The base color (red, green, blue) and transparency (alpha).

The material value is the linear base color factor and defaults to ColorF.White. The material texture map is sRGB compressed and is sampled from the red, green, blue and alpha channels. If null, ModelTexture.White will be used for rendering.

See also: Material.BaseColorMutable

Displacement

[Constant]
public attribute Displacement → (get)

value : IMaterialPart<float32>: [not-null]
The material part.

The displacement along the surface normal vector.

The material value gives the maximum displacement amount in model-space and defaults to 0. The material texture map is not sRGB compressed and is sampled from the red channel by default. If null, ModelTexture.DisplacementZero will be used for rendering.

See also: Material.DisplacementMutable

Emissive

[Constant]
public attribute Emissive → (get)

value : IMaterialPart<ColorF>: [not-null]
The material part.

The emissive color.

The material value gives the linear emissive color factor and defaults to ColorF.Black. The material texture map is sRGB compressed and is sampled from the red, green and blue channels. If null, ModelTexture.Black will be used for rendering.

See also: Material.EmissiveMutable

Glossiness

[Constant]
public attribute Glossiness → (get)

value : IMaterialPart<float32>: [not-null]
The material part.

The amount of glossiness (specular-glossiness PBR workflow only).

The material value gives the linear glossiness factor and defaults to 0. The material texture map is not sRGB compressed and is sampled from the red channel by default. If null, ModelTexture.White will be used for rendering.

See also: Material.GlossinessMutable

LineThickness

public attribute LineThickness → (get)

value : float32: The line thickness for opaque line geometry, in screen pixels. Will be clamped to the supported range (see remarks).

The thickness to use for opaque line geometry.

At render time, the ILineFeatureLevels.FeatureLevel of the graphics context will be used to clamp the line thickness to the supported range.

Defaults to 1.

Metalness

[Constant]
public attribute Metalness → (get)

value : IMaterialPart<float32>: [not-null]
The material part.

The amount of metalness.

The material value gives the linear metalness factor for the metallic-roughness PBR workflow in the range [0..1] or negative to choose the specular-glossiness PBR workflow. It defaults to -1. The material texture map is not sRGB compressed and is sampled from the red channel by default. If null, ModelTexture.White will be used for rendering.

See also: Material.MetalnessMutable

Mutable

[Constant]
public attribute Mutable → (get)

value : Material: [not-null]
The mutable Material reference.

Returns the mutable Material reference for this material.

See also: IMaterial.Copy

Normal

[Constant]
public attribute Normal → (get)

value : IMaterialPart<float32>: [not-null]
The material part.

The surface normals.

The material value is the scale factor that will be applied to the X- and Y-components of the normal-vectors that are encoded in the material texture, before normalizing them. It defaults to 1. The material texture is not sRGB compressed and is sampled from the red, green and blue channels. If null, ModelTexture.NormalUpRGB will be used for rendering.

See also: Material.NormalMutable

Occlusion

[Constant]
public attribute Occlusion → (get)

value : IMaterialPart<float32>: [not-null]
The material part.

The ambient occlusion.

The material values gives the ambient occlusion strength: 0 will disable ambient occlusion and a value of 1 will show full ambient occlusion. It defaults to 1. The material texture is not sRGB compressed and is sampled from the red channel by default. If null, ModelTexture.White will be used for rendering.

See also: Material.OcclusionMutable

Opacity

[Constant]
public attribute Opacity → (get)

value : IMaterialPart<float32>: [not-null]
The material part.

The opacity.

The material value specifies the alpha cutoff threshold: if the computed alpha value is less than the cutoff threshold, the alpha value 0 will be used for rendering. Otherwise, the alpha value 1 will be used. If 0, the opacity cutoff will be disabled and alpha blending / alpha-to-coverage will be used. It defaults to 0. The material texture is not sRGB compressed and is sampled from the red channel by default. If null, ModelTexture.White will be used for rendering.

See also: Material.OpacityMutable
ModelPartFlags.Opaque

Reflectivity

[Constant]
public attribute Reflectivity → (get)

value : IMaterialPart<ColorF>: [not-null]
The material part.

The surface reflectivity.

The material value defaults to (0.04, 0.04, 0.04), which is the pure-white diffuse reflectivity for an index of refraction of 1.5, see Material.ReflectivityDefaultColor. The material texture is sRGB compressed and is sampled from the red, green and blue channels. If null, ModelTexture.White will be used for rendering.

See also: Material.ReflectivityMutable

Refraction

public attribute Refraction → (get)

value : float32: The index of refraction.

The index of refraction.

Defaults to Material.RefractionDefault.

Roughness

[Constant]
public attribute Roughness → (get)

value : IMaterialPart<float32>: [not-null]
The material part.

The amount of roughness (metallic-roughness PBR workflow only).

The material value gives the linear roughness factor and defaults to 1. The material texture map is not sRGB compressed and is sampled from the green channel by default. If null, ModelTexture.White will be used for rendering.

See also: Material.RoughnessMutable

Specularity

[Constant]
public attribute Specularity → (get)

value : IMaterialPart<float32>: [not-null]
The material part.

The amount of specularity.

The material value gives the linear specularity factors and defaults to 1. The material texture is not sRGB compressed and is sampled from the alpha channel by default. If null, ModelTexture.White will be used for rendering.

See also: Material.SpecularityMutable

Translucency

[Constant]
public attribute Translucency → (get)

value : IMaterialPart<ColorF>: [not-null]
The material part.

The amount of translucency.

The material value is the linear translucency color factor and defaults to ColorF.Black. The material texture map is sRGB compressed and is sampled from the red, green and blue. If null, ModelTexture.Black will be used for rendering.

See also: Material.TranslucencyMutable

Transmission

[Constant]
public attribute Transmission → (get)

value : IMaterialPart<float32>: [not-null]
The material part.

The transmission of light.

The material value gives the linear transmission factor and defaults to 0. The material texture map is not sRGB compressed and is sampled from the red channel by default. If null, ModelTexture.White will be used for rendering.

See also: Material.TransmissionMutable