PbrMaterial¶

class PbrMaterial¶

Bases: TypedWritableReferenceCount, Namable

The parameters of a physically based surface, shaped after glTF 2.0’s metallic-roughness model and its KHR_materials_ior, KHR_materials_specular, KHR_materials_emissive_strength and KHR_materials_unlit extensions. Put it on a node with PbrMaterialAttrib; PbrShaderGenerator then shades the node.

Textures are not stored here: the core maps live in the node’s TextureAttrib, one TextureStage each, told apart by the stage’s mode (M_modulate: base colour, M_metallic_roughness: metallic in B and roughness in G, M_occlusion_metallic_roughness: the same plus occlusion in R, M_occlusion, M_normal, M_emission). The stage’s texcoord name picks the UV set and a TexMatrixAttrib on the stage its transform (KHR_texture_transform). Every Acron model loader, set_texture override and texture tool therefore keeps working. Each factor here multiplies its map, as in glTF.

Units: emission is in nits (cd/m^2): the surface emits emissive * emissive_strength. Colours are linear Rec. 709.

The scalar parameters are live: a change shows on the next frame without a new shader. The ones that select a shader permutation (alpha mode, double-sidedness, the shading model) make the generator re-specialise the states that use the material.

Inheritance diagram

digraph inheritancee7f6089c19 { bgcolor=transparent; rankdir=BT; size="8.0, 12.0"; "DTOOL_SUPER_BASE" [fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style=""]; "Namable" [URL="acron.core.Namable.html#acron.core.Namable",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "DTOOL_SUPER_BASE" -> "Namable" [arrowsize=0.75,style=""]; "PbrMaterial" [URL="acron.shading.PbrMaterial.html#acron.shading.PbrMaterial",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "TypedWritableReferenceCount" -> "PbrMaterial" [arrowsize=0.75,style=""]; "Namable" -> "PbrMaterial" [arrowsize=0.75,style=""]; "ReferenceCount" [URL="acron.core.ReferenceCount.html#acron.core.ReferenceCount",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "DTOOL_SUPER_BASE" -> "ReferenceCount" [arrowsize=0.75,style=""]; "TypedObject" [URL="acron.core.TypedObject.html#acron.core.TypedObject",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "DTOOL_SUPER_BASE" -> "TypedObject" [arrowsize=0.75,style=""]; "TypedWritable" [URL="acron.core.TypedWritable.html#acron.core.TypedWritable",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "TypedObject" -> "TypedWritable" [arrowsize=0.75,style=""]; "TypedWritableReferenceCount" [URL="acron.core.TypedWritableReferenceCount.html#acron.core.TypedWritableReferenceCount",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=11,height=0.25,shape=box,style="",target="_top",tooltip="/**"]; "TypedWritable" -> "TypedWritableReferenceCount" [arrowsize=0.75,style=""]; "ReferenceCount" -> "TypedWritableReferenceCount" [arrowsize=0.75,style=""]; }

enum AlphaMode¶

enumerator AM_opaque = 0¶

enumerator AM_mask = 1¶

enumerator AM_blend = 2¶

enum ShadingModel¶

enumerator SM_standard = 0¶

enumerator SM_unlit = 1¶

PbrMaterial.__init__()¶

A white dielectric: base colour 1, metallic 0, roughness 0.5, ior 1.5. glTF’s own factor defaults (metallic 1, roughness 1) describe a rough white metal, which is what a material without maps would then be; a glTF loader sets every factor explicitly, from glTF’s defaults.

A copy has its own uniform rows (changing it leaves the original alone) and is not yet used by any shader.

PbrMaterial.assign()¶

PbrMaterial.compare_values()¶: True if every parameter (not the name) equals the other material’s.

static PbrMaterial.from_material()¶: A PbrMaterial with the values of one of Acron’s Materials, for models that carry only those: the base colour (or, without one, the diffuse colour), metallic, roughness (Acron derives it from the shininess when unset), the emission (taken as nits) and the refractive index (an index of 1 or less, Acron’s “unset”, gives 1.5).

PbrMaterial.get_alpha_cutoff()¶: The alpha below which a masked surface is discarded (glTF default 0.5).

PbrMaterial.get_alpha_mode()¶: How alpha is used: opaque (ignored), mask (cut at alpha_cutoff) or blend (written out; the node also needs a TransparencyAttrib).

PbrMaterial.get_base_color()¶: The base colour factor (linear, with alpha), which multiplies the base colour map and the vertex colour.

static PbrMaterial.get_class_type()¶

PbrMaterial.get_double_sided()¶: True if back faces are lit as seen from their own side (the normal is flipped). Culling is the node’s CullFaceAttrib, as for any geometry.

PbrMaterial.get_emission()¶: The emitted radiance, in nits per channel: emissive * emissive_strength.

PbrMaterial.get_emission_luminance()¶: The luminance of the emission, in nits.

PbrMaterial.get_emissive()¶: The emissive colour factor (glTF emissiveFactor).

PbrMaterial.get_emissive_strength()¶: The emissive strength (KHR_materials_emissive_strength): emission in nits is emissive * emissive_strength.

PbrMaterial.get_f0_dielectric()¶: The dielectric reflectance at normal incidence that the shader derives: ((ior - 1) / (ior + 1))^2 * specular_color * specular_factor, each channel at most 1.

PbrMaterial.get_ior()¶: The index of refraction of a dielectric (KHR_materials_ior; 1.5 by default, which gives f0 = 0.04).

PbrMaterial.get_metallic()¶: Metalness, 0 (dielectric) to 1 (metal); multiplies the map’s B channel.

PbrMaterial.get_normal_scale()¶: glTF normalTexture.scale: scales the normal map’s X and Y.

PbrMaterial.get_occlusion_strength()¶: glTF occlusionTexture.strength: 0 ignores the occlusion map, 1 applies it fully.

PbrMaterial.get_roughness()¶: Perceptual roughness, 0 to 1 (GGX alpha is its square); multiplies the map’s G channel. The shader clamps it to at least 0.045.

PbrMaterial.get_shading_model()¶: SM_standard (metallic-roughness) or SM_unlit (KHR_materials_unlit: the base colour is written as it is, unexposed).

PbrMaterial.get_specular_color()¶: KHR_materials_specular’s specularColorFactor: tints the dielectric f0.

PbrMaterial.get_specular_factor()¶: KHR_materials_specular’s specularFactor: scales the dielectric Fresnel (f0 and f90). 0 leaves a purely diffuse dielectric.

PbrMaterial.output()¶

PbrMaterial.set_alpha_cutoff()¶

PbrMaterial.set_alpha_mode()¶

PbrMaterial.set_base_color()¶

PbrMaterial.set_double_sided()¶

PbrMaterial.set_emission_luminance()¶: Sets the emission from a colour (only its chromaticity counts) and a luminance in nits: emissive becomes the colour scaled to a luminance of 1, emissive_strength the luminance. A black colour emits nothing.

PbrMaterial.set_emissive()¶

PbrMaterial.set_emissive_strength()¶

PbrMaterial.set_ior()¶

PbrMaterial.set_metallic()¶

PbrMaterial.set_normal_scale()¶

PbrMaterial.set_occlusion_strength()¶

PbrMaterial.set_roughness()¶

PbrMaterial.set_shading_model()¶

PbrMaterial.set_specular_color()¶

PbrMaterial.set_specular_factor()¶

PbrMaterial.write()¶