Describes the surface appearance and render state of Mesh geometry. More...

#include <a3d/visual/material/Material.h>

Public Types
enum class	PropertyType : uint8_t { Ambient = 0 , Diffuse = 1 , Specular = 2 , Emission = 3 }
	Identifies one of the material's lighting properties. More...

enum class	FillMode { Fill , Lines , Points }
	Selects polygon rasterization mode. More...

enum class	AlphaMode : uint8_t { Opaque , Mask , Blend }
	Selects how material alpha participates in render-pass selection. More...

enum class	BlendFunction : uint8_t { Disabled , Alpha , Additive , PremultipliedAlpha }
	Selects the blending function used for transparent materials. More...

using	Property = std::variant< std::monostate, std::shared_ptr< Texture >, Color >
	Material property contents: absent, a shared Texture, or a constant Color. More...

Public Member Functions
	Material ()
	Creates a Material with no lighting properties and default render state. More...

	Material (const Property &ambient, const Property &diffuse, const Property &specular)
	Creates a Material with the supplied ambient, diffuse, and specular properties. More...

	Material (const Property &ambient, const Property &diffuse, const Property &specular, const Property &emission)
	Creates a Material with the supplied lighting properties. More...

const std::optional< std::string > &	name () const
	Returns the optional material name. More...

void	name (const std::string &name)
	Sets the material name. More...

const Property &	ambient () const
	Returns the ambient material property. More...

void	ambient (const Property &ambient)
	Sets the ambient material property. More...

const Property &	diffuse () const
	Returns the diffuse material property. More...

void	diffuse (const Property &diffuse)
	Sets the diffuse material property. More...

const Property &	specular () const
	Returns the specular material property. More...

void	specular (const Property &specular)
	Sets the specular material property. More...

const Property &	emission () const
	Returns the self-emissive material property. More...

void	emission (const Property &emission)
	Sets the self-emissive material property. More...

float	specularExponent () const
	Returns the Phong specular exponent controlling highlight sharpness. More...

void	specularExponent (float exponent)
	Sets the Phong specular exponent controlling highlight sharpness. More...

bool	locksAmbientWithDiffuse () const
	Returns whether diffuse content replaces ambient content during lighting. More...

void	locksAmbientWithDiffuse (bool flag)
	Sets whether diffuse content replaces ambient content during lighting. More...

bool	doubleSided () const
	Returns whether both sides of polygons are rendered. More...

void	doubleSided (bool flag)
	Sets whether both sides of polygons are rendered. More...

FillMode	fillMode () const
	Returns the polygon rasterization mode. More...

void	fillMode (FillMode mode)
	Sets the polygon rasterization mode. More...

float	uvScale () const
	Returns the uniform texture-coordinate scale. More...

void	uvScale (float scale)
	Sets the uniform texture-coordinate scale. More...

AlphaMode	alphaMode () const
	Returns the alpha render mode. More...

void	alphaMode (AlphaMode mode)
	Sets the alpha render mode. More...

float	alphaCutoff () const
	Returns the stored alpha-mask cutoff; the renderer does not currently consume this value. More...

void	alphaCutoff (float v)
	Sets the stored alpha-mask cutoff; the renderer does not currently consume this value. More...

BlendFunction	blendFunction () const
	Returns the requested transparent blending function. More...

void	blendFunction (BlendFunction function)
	Sets the requested transparent blending function. More...

bool	depthTestEnabled () const
	Returns whether depth testing is enabled for the material. More...

void	depthTestEnabled (bool enabled)
	Enables or disables depth testing for the material. More...

bool	depthWriteEnabled () const
	Returns whether rendering the material writes to the depth buffer. More...

void	depthWriteEnabled (bool enabled)
	Enables or disables depth-buffer writes for the material. More...

Static Public Member Functions
static std::shared_ptr< Material >	DefaultMaterial ()
	Returns the shared mutable fallback Material used for geometry without a usable material. More...

static std::shared_ptr< Material >	DiffuseMaterial (Property property)
	Creates a Material containing only the supplied diffuse `property`. More...

static std::shared_ptr< Material >	EmissionMaterial (Property property)
	Creates a Material containing only the supplied emission `property`. More...

Detailed Description

Describes the surface appearance and render state of Mesh geometry.

Ambient, diffuse, specular, and emission properties may be absent, a constant Color, or a shared Texture. Copying a Material copies its values while retaining shared ownership of any Texture objects referenced by its properties.

Definition at line 34 of file Material.h.

Member Typedef Documentation

◆ Property

using a3d::Material::Property = std::variant<std::monostate, std::shared_ptr<Texture>, Color>

Material property contents: absent, a shared Texture, or a constant Color.

Definition at line 40 of file Material.h.

Member Enumeration Documentation

◆ AlphaMode

enum class a3d::Material::AlphaMode : uint8_t

strong

Selects how material alpha participates in render-pass selection.

Enumerator
Opaque	Selects the opaque render pass.
Mask	Selects the cutout/masked render pass.
Blend	Selects the transparent blending render pass.

Definition at line 58 of file Material.h.

◆ BlendFunction

enum class a3d::Material::BlendFunction : uint8_t

strong

Selects the blending function used for transparent materials.

Enumerator
Disabled	Do not explicitly enable blending.
Alpha	Conventional source-alpha blending.
Additive	Add source color to the destination.
PremultipliedAlpha	Alpha blending for premultiplied source color.

Definition at line 68 of file Material.h.

◆ FillMode

enum class a3d::Material::FillMode

strong

Selects polygon rasterization mode.

Enumerator
Fill	Rasterize filled polygons.
Lines	Rasterize polygon edges.
Points	Rasterize polygon vertices as points.

Definition at line 51 of file Material.h.

◆ PropertyType

enum class a3d::Material::PropertyType : uint8_t

strong

Identifies one of the material's lighting properties.

Enumerator
Ambient	Ambient reflectance.
Diffuse	Diffuse reflectance and base surface color.
Specular	Specular reflectance.
Emission	Self-emissive surface content.

Definition at line 43 of file Material.h.

Constructor & Destructor Documentation

◆ Material() [1/3]

a3d::Material::Material ( )

Creates a Material with no lighting properties and default render state.

◆ Material() [2/3]

a3d::Material::Material	(	const Property &	ambient,
		const Property &	diffuse,
		const Property &	specular
	)

Creates a Material with the supplied ambient, diffuse, and specular properties.

◆ Material() [3/3]

a3d::Material::Material	(	const Property &	ambient,
		const Property &	diffuse,
		const Property &	specular,
		const Property &	emission
	)

Creates a Material with the supplied lighting properties.

Member Function Documentation

◆ alphaCutoff() [1/2]

float a3d::Material::alphaCutoff ( ) const

Returns the stored alpha-mask cutoff; the renderer does not currently consume this value.

◆ alphaCutoff() [2/2]

void a3d::Material::alphaCutoff ( float v )

Sets the stored alpha-mask cutoff; the renderer does not currently consume this value.

◆ alphaMode() [1/2]

AlphaMode a3d::Material::alphaMode ( ) const

Returns the alpha render mode.

◆ alphaMode() [2/2]

void a3d::Material::alphaMode ( AlphaMode mode )

Sets the alpha render mode.

◆ ambient() [1/2]

const Property & a3d::Material::ambient ( ) const

Returns the ambient material property.

◆ ambient() [2/2]

void a3d::Material::ambient ( const Property & ambient )

Sets the ambient material property.

◆ blendFunction() [1/2]

BlendFunction a3d::Material::blendFunction ( ) const

Returns the requested transparent blending function.

◆ blendFunction() [2/2]

void a3d::Material::blendFunction ( BlendFunction function )

Sets the requested transparent blending function.

Opaque and Mask materials render with blending disabled. A Blend material with BlendFunction::Disabled uses conventional alpha blending by default.

◆ DefaultMaterial()

static std::shared_ptr< Material > a3d::Material::DefaultMaterial ( )

static

Returns the shared mutable fallback Material used for geometry without a usable material.

The same Material instance is returned on each call, so modifying it changes the fallback appearance for all users of the default material.

◆ depthTestEnabled() [1/2]

bool a3d::Material::depthTestEnabled ( ) const

Returns whether depth testing is enabled for the material.

◆ depthTestEnabled() [2/2]

void a3d::Material::depthTestEnabled ( bool enabled )

Enables or disables depth testing for the material.

◆ depthWriteEnabled() [1/2]

bool a3d::Material::depthWriteEnabled ( ) const

Returns whether rendering the material writes to the depth buffer.

◆ depthWriteEnabled() [2/2]

void a3d::Material::depthWriteEnabled ( bool enabled )

Enables or disables depth-buffer writes for the material.

◆ diffuse() [1/2]

const Property & a3d::Material::diffuse ( ) const

Returns the diffuse material property.

◆ diffuse() [2/2]

void a3d::Material::diffuse ( const Property & diffuse )

Sets the diffuse material property.

◆ DiffuseMaterial()

static std::shared_ptr< Material > a3d::Material::DiffuseMaterial ( Property property )

static

Creates a Material containing only the supplied diffuse property.

◆ doubleSided() [1/2]

bool a3d::Material::doubleSided ( ) const

Returns whether both sides of polygons are rendered.

◆ doubleSided() [2/2]

void a3d::Material::doubleSided ( bool flag )

Sets whether both sides of polygons are rendered.

◆ emission() [1/2]

const Property & a3d::Material::emission ( ) const

Returns the self-emissive material property.

◆ emission() [2/2]

void a3d::Material::emission ( const Property & emission )

Sets the self-emissive material property.

When emission content is present, the standard material shader renders it without evaluating Scene lights.

◆ EmissionMaterial()

static std::shared_ptr< Material > a3d::Material::EmissionMaterial ( Property property )

static

Creates a Material containing only the supplied emission property.

◆ fillMode() [1/2]

FillMode a3d::Material::fillMode ( ) const

Returns the polygon rasterization mode.

◆ fillMode() [2/2]

void a3d::Material::fillMode ( FillMode mode )

Sets the polygon rasterization mode.

Support for non-filled modes is rendering-backend dependent.

◆ locksAmbientWithDiffuse() [1/2]

bool a3d::Material::locksAmbientWithDiffuse ( ) const

Returns whether diffuse content replaces ambient content during lighting.

◆ locksAmbientWithDiffuse() [2/2]

void a3d::Material::locksAmbientWithDiffuse ( bool flag )

Sets whether diffuse content replaces ambient content during lighting.

◆ name() [1/2]

const std::optional< std::string > & a3d::Material::name ( ) const

Returns the optional material name.

◆ name() [2/2]

void a3d::Material::name ( const std::string & name )

Sets the material name.

◆ specular() [1/2]

const Property & a3d::Material::specular ( ) const

Returns the specular material property.

◆ specular() [2/2]

void a3d::Material::specular ( const Property & specular )

Sets the specular material property.

◆ specularExponent() [1/2]

float a3d::Material::specularExponent ( ) const

Returns the Phong specular exponent controlling highlight sharpness.

◆ specularExponent() [2/2]

void a3d::Material::specularExponent ( float exponent )

Sets the Phong specular exponent controlling highlight sharpness.

◆ uvScale() [1/2]

float a3d::Material::uvScale ( ) const

Returns the uniform texture-coordinate scale.

Texture coordinates are divided by this value; values greater than one enlarge texture features and values below one increase repetition.

◆ uvScale() [2/2]

void a3d::Material::uvScale ( float scale )

Sets the uniform texture-coordinate scale.

Exceptions

std::invalid_argument if scale is less than or equal to zero.

The documentation for this class was generated from the following file:

a3d/visual/material/Material.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ Property

Member Enumeration Documentation

◆ AlphaMode

◆ BlendFunction

◆ FillMode

◆ PropertyType

Constructor & Destructor Documentation

◆ Material() [1/3]

◆ Material() [2/3]

◆ Material() [3/3]

Member Function Documentation

◆ alphaCutoff() [1/2]

◆ alphaCutoff() [2/2]

◆ alphaMode() [1/2]

◆ alphaMode() [2/2]

◆ ambient() [1/2]

◆ ambient() [2/2]

◆ blendFunction() [1/2]

◆ blendFunction() [2/2]

◆ DefaultMaterial()

◆ depthTestEnabled() [1/2]

◆ depthTestEnabled() [2/2]

◆ depthWriteEnabled() [1/2]

◆ depthWriteEnabled() [2/2]

◆ diffuse() [1/2]

◆ diffuse() [2/2]

◆ DiffuseMaterial()

◆ doubleSided() [1/2]

◆ doubleSided() [2/2]

◆ emission() [1/2]

◆ emission() [2/2]

◆ EmissionMaterial()

◆ fillMode() [1/2]

◆ fillMode() [2/2]

◆ locksAmbientWithDiffuse() [1/2]

◆ locksAmbientWithDiffuse() [2/2]

◆ name() [1/2]

◆ name() [2/2]

◆ specular() [1/2]

◆ specular() [2/2]

◆ specularExponent() [1/2]

◆ specularExponent() [2/2]

◆ uvScale() [1/2]

◆ uvScale() [2/2]