Description of a surface for rendering purposes. More...

Inherits G3D::Material.

Classes
class	Specification
	Specification of a material; used for loading. More...

Public Member Functions
AlphaFilter	alphaFilter () const

const shared_ptr< UniversalBSDF > &	bsdf () const
	Never nullptr. More...

const shared_ptr< BumpMap > &	bump () const
	May be nullptr. More...

double	constant (const String &name) const
	Returns nan() if the constant is not bound. More...

virtual bool	coverageLessThanEqual (const float alphaThreshold, const Point2 &texCoord) const override
	Returns true if this material has an alpha value less than alphaThreshold at texCoord. More...

const String &	customShaderPrefix () const
	For experimentation. More...

const Component3 &	emissive () const
	An emission function. More...

uint8	flags () const

bool	hasAlpha () const

bool	hasEmissive () const

virtual bool	hasPartialCoverage () const override
	Return true if coverageLessThanEqual(1) can ever return true. More...

bool	hasTransmissive () const

bool	inferAmbientOcclusionAtTransparentPixels () const

const Component3 *	lightMap () const
	Directional light maps. More...

const String &	macros () const
	Preprocessor macros for GLSL defining the fields used. More...

MirrorQuality	mirrorHint () const
	Preferred type of mirror reflection quality. More...

virtual const String &	name () const override

int	numLightMapDirections () const
	0, 1, or 3. More...

bool	operator== (const UniversalMaterial &other) const
	To be identical, two materials must not only have the same images in their textures but must share pointers to the same underlying G3D::Texture objects. More...

RefractionHint	refractionHint () const
	Preferred type of refraction quality. More...

virtual void	sample (const Tri &tri, float u, float v, int triIndex, const CPUVertexArray &vertexArray, bool backside, shared_ptr< Surfel > &surfel, float du=0, float dv=0, bool twoSided=true) const override
	Re-uses the existing surfel if it is a UniversalSurfel. More...

const Sampler &	sampler () const
	The sampler used for all Textures. More...

void	setShaderArgs (class UniformTable &a, const String &prefix="") const

void	setStorage (ImageStorage s) const override

Texture::Dimension	textureDimension () const
	Returns the dimension of the textures in the material. More...

bool	validateTextureDimensions () const
	Checks that all textures in the material use the same dimensions, returns true if they do. More...

Static Public Member Functions
static void	clearCache ()
	Flush the material cache. More...

static shared_ptr< UniversalMaterial >	create (const shared_ptr< UniversalBSDF > &bsdf, const Component3 &emissive=Component3(), const shared_ptr< BumpMap > &bump=shared_ptr< BumpMap >(), const Array< Component3 > &lightMaps=Array< Component3 >(), const String &customShaderPrefix="", const AlphaFilter alphaFilter=AlphaFilter::DETECT, const uint8 flags=0)
	The UniversalMaterial::create(const Settings& settings) factor method is recommended over this one because it performs caching and argument validation. More...

static shared_ptr< UniversalMaterial >	create (const Specification &settings=Specification())
	Caches previously created Materials, and the textures within them, to minimize loading time. More...

static shared_ptr< UniversalMaterial >	create (const String &name, const Specification &settings)

static shared_ptr< UniversalMaterial >	createDiffuse (const Color3 &p_Lambertian)
	Create a G3D::UniversalMaterial using a Lambertian (pure diffuse) G3D::BSDF with color p_Lambertian. More...

static shared_ptr< UniversalMaterial >	createDiffuse (const String &textureFilename)

static shared_ptr< UniversalMaterial >	createDiffuse (const shared_ptr< Texture > &texture)
	Create a G3D::UniversalMaterial using the texture as the Lambertian (pure diffuse), with no emissive or bump. More...

static shared_ptr< UniversalMaterial >	createEmpty ()
	Constructs an empty UniversalMaterial, which has no BSDF. More...

Protected Member Functions
	UniversalMaterial ()

void	computeDefines (String &defines) const
	Appends a string of GLSL macros (e.g., "#define LAMBERTIANMAP\n") to defines that describe the specified components of this G3D::UniversalMaterial, as used by G3D::Shader. More...

Static Protected Member Functions
template<class T , class ... ArgTypes>
static shared_ptr< T >	createShared (ArgTypes &&... args)
	Like std::make_shared, but works for protected constructors. More...

Protected Attributes
AlphaFilter	m_alphaFilter

shared_ptr< UniversalBSDF >	m_bsdf
	Scattering function. More...

shared_ptr< BumpMap >	m_bump
	Bump map. More...

Table< String, double >	m_constantTable
	These constants are also in the m_macros string. More...

String	m_customShaderPrefix
	For experimentation. More...

Component3	m_emissive
	Emission map. More...

uint8	m_flags

bool	m_inferAmbientOcclusionAtTransparentPixels

Component3	m_lightMap [3]
	Directional light maps. More...

String	m_macros

MirrorQuality	m_mirrorHint
	Preferred level of mirror reflection quality. More...

String	m_name

bool	m_needsComputeDefines = true
	Are the macros out of date? More...

int	m_numLightMapDirections

RefractionHint	m_refractionHint
	Preferred level of refraction quality. More...

Sampler	m_sampler

Detailed Description

Description of a surface for rendering purposes.

Encodes a BSDF, bump map, emission function, and flags.

Note that for real-time rendering most translucent surfaces should be two-sided and have comparatively low diffuse terms. They should also be applied to convex objects (subdivide non-convex objects) to prevent rendering surfaces out of order. For ray tracing, implement translucent surfaces as two single-sided surfaces: one for entering the material and one for exiting it (i.e., the "backfaces"). The eta of the exiting surface should be that of the medium that is being exited into–typically, air. So a glass sphere is a set of front faces with eta ~= 1.3 and a set of backfaces with eta = 1.0.

See also: G3D::UniversalBSDF, G3D::Component, G3D::Texture, G3D::BumpMap, G3D::ArticulatedModel, G3D::GBuffer

Constructor & Destructor Documentation

◆ UniversalMaterial()

G3D::UniversalMaterial::UniversalMaterial ( )

protected

Member Function Documentation

◆ alphaFilter()

AlphaFilter G3D::UniversalMaterial::alphaFilter ( ) const

inline

◆ bsdf()

const shared_ptr<UniversalBSDF>& G3D::UniversalMaterial::bsdf ( ) const

inline

Never nullptr.

◆ bump()

const shared_ptr<BumpMap>& G3D::UniversalMaterial::bump ( ) const

inline

May be nullptr.

Referenced by G3D::UniversalMaterial::Specification::setBump().

◆ clearCache()

static void G3D::UniversalMaterial::clearCache ( )

static

Flush the material cache.

If you're editing texture maps on disk and want to reload them, invoke this first.

◆ computeDefines()

void G3D::UniversalMaterial::computeDefines ( String & defines ) const

protected

Appends a string of GLSL macros (e.g., "#define LAMBERTIANMAP\n") to defines that describe the specified components of this G3D::UniversalMaterial, as used by G3D::Shader.

See also: macros()

Referenced by macros().

◆ constant()

double G3D::UniversalMaterial::constant ( const String & name ) const

inline

Returns nan() if the constant is not bound.

◆ coverageLessThanEqual()

virtual bool G3D::UniversalMaterial::coverageLessThanEqual	(	const float	alphaThreshold,
		const Point2 &	texCoord
	)		const

overridevirtual

Returns true if this material has an alpha value less than alphaThreshold at texCoord.

Implements G3D::Material.

◆ create() [1/3]

static shared_ptr<UniversalMaterial> G3D::UniversalMaterial::create	(	const shared_ptr< UniversalBSDF > &	bsdf,
		const Component3 &	emissive = `Component3()`,
		const shared_ptr< BumpMap > &	bump = `shared_ptr< BumpMap >()`,
		const Array< Component3 > &	lightMaps = `Array< Component3 >()`,
		const String &	customShaderPrefix = `""`,
		const AlphaFilter	alphaFilter = `AlphaFilter::DETECT`,
		const uint8	flags = `0`
	)

static

The UniversalMaterial::create(const Settings& settings) factor method is recommended over this one because it performs caching and argument validation.

Deprecated:

◆ create() [2/3]

static shared_ptr<UniversalMaterial> G3D::UniversalMaterial::create ( const Specification & settings = Specification() )

static

Caches previously created Materials, and the textures within them, to minimize loading time.

Materials are initially created with all data stored exclusively on the GPU. Call setStorage() to move or copy data to the CPU (note: it will automatically copy to the CPU as needed, but that process is not threadsafe).

◆ create() [3/3]

static shared_ptr<UniversalMaterial> G3D::UniversalMaterial::create	(	const String &	name,
		const Specification &	settings
	)

static

◆ createDiffuse() [1/3]

static shared_ptr<UniversalMaterial> G3D::UniversalMaterial::createDiffuse ( const Color3 & p_Lambertian )

static

Create a G3D::UniversalMaterial using a Lambertian (pure diffuse) G3D::BSDF with color p_Lambertian.

◆ createDiffuse() [2/3]

static shared_ptr<UniversalMaterial> G3D::UniversalMaterial::createDiffuse ( const String & textureFilename )

static

◆ createDiffuse() [3/3]

static shared_ptr<UniversalMaterial> G3D::UniversalMaterial::createDiffuse ( const shared_ptr< Texture > & texture )

static

Create a G3D::UniversalMaterial using the texture as the Lambertian (pure diffuse), with no emissive or bump.

◆ createEmpty()

static shared_ptr<UniversalMaterial> G3D::UniversalMaterial::createEmpty ( )

static

Constructs an empty UniversalMaterial, which has no BSDF.

This is provided mainly for efficiency when constructing a UniversalMaterial manually. Use UniversalMaterial::create() to create a default material.

◆ createShared()

template<class T , class ... ArgTypes>

static shared_ptr<T> G3D::ReferenceCountedObject::createShared ( ArgTypes &&... args )

inlinestaticprotectedinherited

Like std::make_shared, but works for protected constructors.

Call as createShared<myclass>.

◆ customShaderPrefix()

const String& G3D::UniversalMaterial::customShaderPrefix ( ) const

inline

For experimentation.

This code (typically macro definitions) is injected into the shader code after the material constants.

◆ emissive()

const Component3& G3D::UniversalMaterial::emissive ( ) const

inline

An emission function.

Dim emission functions are often used for "glow", where a surface is bright independent of external illumination but does not illuminate other surfaces.

Bright emission functions are used for light sources under the photon mapping algorithm.

The result is not a pointer because G3D::Component3 is immutable and already indirects the G3D::Component::MapComponent inside of it by a pointer.

◆ flags()

uint8 G3D::UniversalMaterial::flags ( ) const

inline

See also: Surfel::flags

◆ hasAlpha()

bool G3D::UniversalMaterial::hasAlpha ( ) const

◆ hasEmissive()

bool G3D::UniversalMaterial::hasEmissive ( ) const

◆ hasPartialCoverage()

virtual bool G3D::UniversalMaterial::hasPartialCoverage ( ) const

overridevirtual

Return true if coverageLessThanEqual(1) can ever return true.

Implements G3D::Material.

◆ hasTransmissive()

bool G3D::UniversalMaterial::hasTransmissive ( ) const

◆ inferAmbientOcclusionAtTransparentPixels()

bool G3D::UniversalMaterial::inferAmbientOcclusionAtTransparentPixels ( ) const

inline

◆ lightMap()

const Component3* G3D::UniversalMaterial::lightMap ( ) const

inline

Directional light maps.

These are treated as additional incoming light on the surface.

If numLightMapDirections is 0, this is unused.

If numLightMapDirections is 1, incident light is stored in lightMap[0] and is assumed to be at normal incidence, i.e., coming from wi = (0, 0, 1) in tangent space, where the axes are t1, t2, and n.

If numLightMapDirections is 3, incident light is stored in lightMap[0..3] and follows the HL2 basis (see "Radiosity normal mapping" http://www2.ati.com/developer/gdc/D3DTutorial10_Half-Life2_Shading.pdf):

lightMap[0] is light incoming from (sqrt(2/3), 0, 1/sqrt(3)),
lightMap[1] is light incoming from (-1/sqrt(6), 1/sqrt(2), 1/sqrt(3)),
lightMap[2] is light incoming from (-1/sqrt(6), -1/sqrt(2), 1/sqrt(3)).

◆ macros()

const String& G3D::UniversalMaterial::macros ( ) const

inline

Preprocessor macros for GLSL defining the fields used.

◆ mirrorHint()

MirrorQuality G3D::UniversalMaterial::mirrorHint ( ) const

inline

Preferred type of mirror reflection quality.

The actual type available depends on the renderer.

◆ name()

virtual const String& G3D::UniversalMaterial::name ( ) const

inlineoverridevirtual

Implements G3D::Material.

Referenced by constant(), and G3D::UniversalMaterial::Specification::setConstant().

◆ numLightMapDirections()

int G3D::UniversalMaterial::numLightMapDirections ( ) const

inline

0, 1, or 3.

See also: lightMap

◆ operator==()

bool G3D::UniversalMaterial::operator== ( const UniversalMaterial & other ) const

inline

To be identical, two materials must not only have the same images in their textures but must share pointers to the same underlying G3D::Texture objects.

◆ refractionHint()

RefractionHint G3D::UniversalMaterial::refractionHint ( ) const

inline

Preferred type of refraction quality.

The actual type available depends on the renderer.

◆ sample()

virtual void G3D::UniversalMaterial::sample	(	const Tri &	tri,
		float	u,
		float	v,
		int	triIndex,
		const CPUVertexArray &	vertexArray,
		bool	backside,
		shared_ptr< Surfel > &	surfel,
		float	du = `0`,
		float	dv = `0`,
		bool	twoSided = `true`
	)		const

overridevirtual

Re-uses the existing surfel if it is a UniversalSurfel.

Implements G3D::Material.

◆ sampler()

const Sampler& G3D::UniversalMaterial::sampler ( ) const

inline

The sampler used for all Textures.

◆ setShaderArgs()

void G3D::UniversalMaterial::setShaderArgs	(	class UniformTable &	a,
		const String &	prefix = `""`
	)		const

See also: uniform_UniversalMaterial

◆ setStorage()

void G3D::UniversalMaterial::setStorage ( ImageStorage s ) const

overridevirtual

Implements G3D::Material.

◆ textureDimension()

Texture::Dimension G3D::UniversalMaterial::textureDimension ( ) const

Returns the dimension of the textures in the material.

◆ validateTextureDimensions()

bool G3D::UniversalMaterial::validateTextureDimensions ( ) const

Checks that all textures in the material use the same dimensions, returns true if they do.

Member Data Documentation

◆ m_alphaFilter

AlphaFilter G3D::UniversalMaterial::m_alphaFilter

protected

Referenced by alphaFilter().

◆ m_bsdf

shared_ptr<UniversalBSDF> G3D::UniversalMaterial::m_bsdf

protected

Scattering function.

Referenced by bsdf(), and operator==().

◆ m_bump

shared_ptr<BumpMap> G3D::UniversalMaterial::m_bump

protected

Bump map.

Referenced by bump(), and operator==().

◆ m_constantTable

Table<String, double> G3D::UniversalMaterial::m_constantTable

protected

These constants are also in the m_macros string.

Referenced by constant().

◆ m_customShaderPrefix

String G3D::UniversalMaterial::m_customShaderPrefix

protected

For experimentation.

This code (typically macro definitions) is injected into the shader code after the material constants.

Referenced by customShaderPrefix().

◆ m_emissive

Component3 G3D::UniversalMaterial::m_emissive

protected

Emission map.

This emits radiance uniformly in all directions.

Referenced by emissive(), and operator==().

◆ m_flags

uint8 G3D::UniversalMaterial::m_flags

protected

Referenced by flags(), and operator==().

◆ m_inferAmbientOcclusionAtTransparentPixels

bool G3D::UniversalMaterial::m_inferAmbientOcclusionAtTransparentPixels

protected

Referenced by inferAmbientOcclusionAtTransparentPixels().

◆ m_lightMap

Component3 G3D::UniversalMaterial::m_lightMap[3]

protected

Directional light maps.

These are treated as additional incoming light on the surface.

If numLightMapDirections is 0, this is unused.

If numLightMapDirections is 1, incident light is stored in lightMap[0] and is assumed to be at normal incidence, i.e., coming from wi = (0, 0, 1) in tangent space, where the axes are t1, t2, and n.

If numLightMapDirections is 3, incident light is stored in lightMap[0..3] and follows the HL2 basis (see "Radiosity normal mapping" http://www2.ati.com/developer/gdc/D3DTutorial10_Half-Life2_Shading.pdf):

lightMap[0] is light incoming from (sqrt(2/3), 0, 1/sqrt(3)),
lightMap[1] is light incoming from (-1/sqrt(6), 1/sqrt(2), 1/sqrt(3)),
lightMap[2] is light incoming from (-1/sqrt(6), -1/sqrt(2), 1/sqrt(3)).

Referenced by lightMap(), and operator==().

◆ m_macros

String G3D::UniversalMaterial::m_macros

protected

Referenced by macros().

◆ m_mirrorHint

MirrorQuality G3D::UniversalMaterial::m_mirrorHint

protected

Preferred level of mirror reflection quality.

The actual level available depends on the renderer.

Referenced by mirrorHint().

◆ m_name

String G3D::UniversalMaterial::m_name

protected

Referenced by name().

◆ m_needsComputeDefines

bool G3D::UniversalMaterial::m_needsComputeDefines = true

protected

Are the macros out of date?

Referenced by macros().

◆ m_numLightMapDirections

int G3D::UniversalMaterial::m_numLightMapDirections

protected

Referenced by numLightMapDirections(), and operator==().

◆ m_refractionHint

RefractionHint G3D::UniversalMaterial::m_refractionHint

protected

Preferred level of refraction quality.

The actual level available depends on the renderer.

Referenced by refractionHint().

◆ m_sampler

Sampler G3D::UniversalMaterial::m_sampler

protected

Referenced by operator==(), and sampler().

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ UniversalMaterial()

Member Function Documentation

◆ alphaFilter()

◆ bsdf()

◆ bump()

◆ clearCache()

◆ computeDefines()

◆ constant()

◆ coverageLessThanEqual()

◆ create() [1/3]

◆ create() [2/3]

◆ create() [3/3]

◆ createDiffuse() [1/3]

◆ createDiffuse() [2/3]

◆ createDiffuse() [3/3]

◆ createEmpty()

◆ createShared()

◆ customShaderPrefix()

◆ emissive()

◆ flags()

◆ hasAlpha()

◆ hasEmissive()

◆ hasPartialCoverage()

◆ hasTransmissive()

◆ inferAmbientOcclusionAtTransparentPixels()

◆ lightMap()

◆ macros()

◆ mirrorHint()

◆ name()

◆ numLightMapDirections()

◆ operator==()

◆ refractionHint()

◆ sample()

◆ sampler()

◆ setShaderArgs()

◆ setStorage()

◆ textureDimension()

◆ validateTextureDimensions()

Member Data Documentation

◆ m_alphaFilter

◆ m_bsdf

◆ m_bump

◆ m_constantTable

◆ m_customShaderPrefix

◆ m_emissive

◆ m_flags

◆ m_inferAmbientOcclusionAtTransparentPixels

◆ m_lightMap

◆ m_macros

◆ m_mirrorHint

◆ m_name

◆ m_needsComputeDefines

◆ m_numLightMapDirections

◆ m_refractionHint

◆ m_sampler