G3D::Material::Specification Class Reference

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

Public Member Functions
	Specification ()
	Specification (const Any &any)
	Construct a Material::Specification from an Any, typically loaded by parsing a file.
	Specification (const Color3 &lambertian)
size_t	hashCode () const
void	load (const std::string &filename)
	Load from a file created by save().
bool	operator!= (const Specification &s) const
bool	operator== (const Specification &s) const
void	removeBump ()
void	removeEmissive ()
void	removeLambertian ()
	Makes the surface opaque black.
void	removeSpecular ()
void	removeTransmissive ()
void	setBump (const std::string &filename, const BumpMap::Settings &settings=BumpMap::Settings(), float normalMapWhiteHeightInPixels=-0.02f)
	The image is assumed to be in linear (R) space.
void	setBump (const BumpMap::Specification &bump)
void	setCustomShaderPrefix (const std::string &s)
void	setDepthWriteHintDistance (float hint)
	Distance below which Surface::depthWriteHint returns true.
void	setEmissive (const std::string &filename, const Color3 &constant=Color3::one())
	The image file is assumed to be in the sRGB color space.
void	setEmissive (const Color3 &constant)
void	setEmissive (const Texture::Specification &spec, const Color3 &constant=Color3::one())
void	setEta (float etaTransmit, float etaReflect)
	Set the index of refraction.
void	setGlossyExponentShininess (int e)
	Same as setShininess(SuperBSDF::packSpecularExponent(e))
void	setLambertian (const std::string &filename, const Color4 &constant=Color4::one())
	Filename of Lambertian (diffuse) term, empty if none.
void	setLambertian (const Texture::Specification &spec, const Color4 &constant=Color4::one())
void	setLambertian (const std::string &filename, float c)
void	setLambertian (const Color4 &constant)
void	setLambertian (float c)
void	setMirrorHint (MirrorQuality q)
	Defaults to G3D::MirrorQuality::STATIC_ENV.
void	setMirrorShininess ()
	Same as setShininess(SuperBSDF::packedSpecularMirror())
void	setRefractionHint (RefractionQuality q)
	Defaults to G3D::RefractionQuality::DYNAMIC_FLAT.
void	setShininess (const std::string &filename, float constant=1.0f)
	The constant multiplies packed values stored in the file.
void	setShininess (const Texture::Specification &spec)
	If a specular filename is set as well, the specular specification overrides all of the settings except for the filename itself.
void	setShininess (float constant)
	Packed sharpness of the specular highlight.
void	setSpecular (const std::string &filename, const Color3 &constant=Color3::one())
	Mirror reflection or glossy reflection.
void	setSpecular (const Color3 &constant)
void	setSpecular (const Texture::Specification &spec, const Color3 &constant=Color3::one())
void	setTransmissive (const std::string &filename, const Color3 &constant=Color3::one())
	This is an approximation of attenuation due to extinction while traveling through a translucent material.
void	setTransmissive (const Color3 &constant)
void	setTransmissive (const Texture::Specification &spec, const Color3 &constant=Color3::one())
Any	toAny () const

Friends
class	Material

Detailed Description

Specification of a material; used for loading.

Can be written to a file or constructed from a series of calls.

The following terminology for photon scattering is used in the G3D::Material::Specification and G3D::BSDF classes and their documentation:

Constructor & Destructor Documentation

G3D::Material::Specification::Specification

(

)

G3D::Material::Specification::Specification

(

const Any &

any

)

Construct a Material::Specification from an Any, typically loaded by parsing a file.

Some simple examples follow.

All fields as texture maps:

Material::Specification {
    lambertian = "diffusemap.png";
    specular = "specmap.png";
    shininess = "shinemap.png";

    transmissive = "transmap.png"; // Simple transmission

    emissive = "emitmap.png";
    emissive = mul("emitmap.png", 3.0); // various options for emissive
    emissive = Color3(0.5);

    bump = "bumpmap.png";  // see BumpMap::Specification

    // Sophisticated transmission
    etatransmit = 1.0;
    extinctionTransmit = Color3(1,1,1);
    etaReflect = 1.0;
    extinctionReflect = Color3(1,1,1);
              
    // Hints and hacks
    refractionHint = "DYNAMIC_FLAT";
    mirrorHint = "STATIC_ENV";
    customShaderPrefix = "";
    depthWriteHintDistance = nan();
}

Diffuse yellow (any Color3 automatically coerces to a pure Lambertian surface):

Color3(1,1,0)

Simple diffuse texture (any string coerces to a filename for the Lambertian texture):

"dirt.jpg"

Mirror:

Material::Specification {
    lambertian = Color3(0.01),
    specular = Color3(0.9),
    shininess = mirror()
}

Red plastic:

Material::Specification {
    lambertian = Color3(0.95, 0.2, 0.05);
    specular = Color3(0.3);
    shininess = glossyExponent(200);
}

Green glass:

Material::Specification {
    lambertian = Color3(0.01, 0.1, 0.05);
    transmissive = Color3(0.01, 0.9, 0.01);
    specular = Color3(0.4);
    shininess = mirror();
}            

See Also

G3D::RefractionQuality,

G3D::MirrorQuality,

G3D::BumpMapSpecification

BETA API Likely to receive incompatible changes in future releases.

G3D::Material::Specification::Specification

(

const Color3 &

lambertian

)

Member Function Documentation

size_t G3D::Material::Specification::hashCode

(

)

const

Referenced by HashTrait< G3D::Material::Specification >::hashCode().

void G3D::Material::Specification::load

(

const std::string &

filename

)

Load from a file created by save().

bool G3D::Material::Specification::operator!= ( const Specification &  s ) const

inline

bool G3D::Material::Specification::operator==

(

const Specification &

s

)

const

void G3D::Material::Specification::removeBump

(

)

void G3D::Material::Specification::removeEmissive

(

)

void G3D::Material::Specification::removeLambertian

(

)

Makes the surface opaque black.

void G3D::Material::Specification::removeSpecular

(

)

void G3D::Material::Specification::removeTransmissive

(

)

void G3D::Material::Specification::setBump	(	const std::string &	filename,
		const BumpMap::Settings &	settings = BumpMap::Settings(),
		float	normalMapWhiteHeightInPixels = -0.02f
	)

The image is assumed to be in linear (R) space.

Parameters

normalMapWhiteHeightInPixels

When loading normal maps, argument used for G3D::GImage::computeNormalMap() whiteHeightInPixels. Default is -0.02f

Deprecated:

void G3D::Material::Specification::setBump ( const BumpMap::Specification &  bump )

inline

void G3D::Material::Specification::setCustomShaderPrefix ( const std::string &  s )

inline

void G3D::Material::Specification::setDepthWriteHintDistance ( float  hint )

inline

Distance below which Surface::depthWriteHint returns true.

• inf() = Always depth write
• -inf() = Never depth write
• nan() [default]: depth write at any distance for opaque and never depth write for transmissive surfaces.

void G3D::Material::Specification::setEmissive	(	const std::string &	filename,
		const Color3 &	constant = Color3::one()
	)

The image file is assumed to be in the sRGB color space.

The constant is multiplied in "linear" space, after sRGB->RGB conversion.

void G3D::Material::Specification::setEmissive

(

const Color3 &

constant

)

void G3D::Material::Specification::setEmissive	(	const Texture::Specification &	spec,
		const Color3 &	constant = Color3::one()
	)

void G3D::Material::Specification::setEta	(	float	etaTransmit,
		float	etaReflect
	)

Set the index of refraction.

Not used unless transmissive is non-zero.

void G3D::Material::Specification::setGlossyExponentShininess ( int  e )

inline

Same as setShininess(SuperBSDF::packSpecularExponent(e))

void G3D::Material::Specification::setLambertian	(	const std::string &	filename,
		const Color4 &	constant = Color4::one()
	)

Filename of Lambertian (diffuse) term, empty if none.

The alpha channel is a mask that will be applied to all maps for coverage. That is, alpha = 0 indicates holes in the surface. Alpha is for partial coverage. Do not use alpha for transparency; set transmissiveFilename instead.

The image file is assumed to be in the sRGB color space. The constant is multiplied in "linear" space, after sRGB->RGB conversion.

Referenced by setLambertian().

void G3D::Material::Specification::setLambertian	(	const Texture::Specification &	spec,
		const Color4 &	constant = Color4::one()
	)

void G3D::Material::Specification::setLambertian ( const std::string &  filename, float  c  )

inline

void G3D::Material::Specification::setLambertian

(

const Color4 &

constant

)

void G3D::Material::Specification::setLambertian ( float  c )

inline

void G3D::Material::Specification::setMirrorHint ( MirrorQuality  q )

inline

Defaults to G3D::MirrorQuality::STATIC_ENV.

void G3D::Material::Specification::setMirrorShininess ( )

inline

Same as setShininess(SuperBSDF::packedSpecularMirror())

void G3D::Material::Specification::setRefractionHint ( RefractionQuality  q )

inline

Defaults to G3D::RefractionQuality::DYNAMIC_FLAT.

void G3D::Material::Specification::setShininess	(	const std::string &	filename,
		float	constant = 1.0f
	)

The constant multiplies packed values stored in the file.

The image is assumed to be in linear (RGB) space.

Referenced by setGlossyExponentShininess(), and setMirrorShininess().

void G3D::Material::Specification::setShininess

(

const Texture::Specification &

spec

)

If a specular filename is set as well, the specular specification overrides all of the settings except for the filename itself.

void G3D::Material::Specification::setShininess

(

float

constant

)

Packed sharpness of the specular highlight.

• SuperBSDF::packedSpecularNone() = no specular term (also forces specular color to black)
• SuperBSDF::packedSpecularMirror() = mirror reflection.
• SuperBSDF::packSpecularExponent(e) affects the size of the glossy hilight, where 1 is dull, 128 is sharp.

void G3D::Material::Specification::setSpecular	(	const std::string &	filename,
		const Color3 &	constant = Color3::one()
	)

Mirror reflection or glossy reflection.

This actually specifies the term, which is the minimum reflectivity of the surface. At glancing angles it will increase towards white.

The image file is assumed to be in the sRGB color space. The constant is multiplied in "linear" space, after sRGB->RGB conversion.

void G3D::Material::Specification::setSpecular

(

const Color3 &

constant

)

void G3D::Material::Specification::setSpecular	(	const Texture::Specification &	spec,
		const Color3 &	constant = Color3::one()
	)

void G3D::Material::Specification::setTransmissive	(	const std::string &	filename,
		const Color3 &	constant = Color3::one()
	)

This is an approximation of attenuation due to extinction while traveling through a translucent material.

Note that no real material is transmissive without also being at least slightly glossy.

The image file is assumed to be in the sRGB color space. The constant is multiplied in "linear" space, after sRGB->RGB conversion.

void G3D::Material::Specification::setTransmissive

(

const Color3 &

constant

)

void G3D::Material::Specification::setTransmissive	(	const Texture::Specification &	spec,
		const Color3 &	constant = Color3::one()
	)

Any G3D::Material::Specification::toAny

(

)

const

Friends And Related Function Documentation

friend class Material

friend