Material Class Reference
[GFX]

A material in Torque 3D is a data structure that describes a surface. More...

Inheritance diagram for Material:

Public Attributes
int	alphaRef
	The alpha reference value for alpha testing. Must be between 0 to 255.
bool	alphaTest
	Enables alpha test when rendering the material.
MaterialAnimType	animFlags [4]
	The types of animation to play on this material.
filename	baseTex [4]
	For backwards compatibility.
bool	bumpAtlas [4]
filename	bumpTex [4]
	For backwards compatibility.
bool	castShadows
	If set to false the lighting system will not cast shadows from this material.
Point2I	cellIndex [4]
Point2I	cellLayout [4]
int	cellSize [4]
ColorF	colorMultiply [4]
	For backwards compatibility.
string	cubemap
	The name of a CubemapData for environment mapping.
filename	detailMap [4]
	A typically greyscale detail texture additively blended into the material.
filename	detailNormalMap [4]
	A second normal map texture applied at the detail scale. You can use the DXTnm format only when per-pixel specular highlights are disabled.
float	detailNormalMapStrength [4]
	Used to scale the strength of the detail normal map when blended with the base normal map.
Point2F	detailScale [4]
	The scale factor for the detail map.
filename	detailTex [4]
	For backwards compatibility.
ColorF	diffuseColor [4]
	This color is multiplied against the diffuse texture color. If no diffuse texture is present this is the material color.
filename	diffuseMap [4]
	The diffuse color texture map.
bool	doubleSided
	Disables backface culling casing surfaces to be double sided. Note that the lighting on the backside will be a mirror of the front side of the surface.
void	dumpInstances
	Dumps a formatted list of the currently allocated material instances for this material to the console.
bool	dynamicCubemap
	Enables the material to use the dynamic cubemap from the ShapeBase object its applied to.
bool	emissive [4]
	Enables emissive lighting for the material.
filename	envMap [4]
	The name of an environment map cube map to apply to this material.
filename	envTex [4]
	For backwards compatibility.
void	flush
	Flushes all material instances that use this material.
string	getAnimFlags
string	getFilename
	Get filename of material.
bool	glow [4]
	Enables rendering this material to the glow buffer.
bool	isAutoGenerated
	Returns true if this Material was automatically generated by MaterialList::mapMaterials().
filename	lightMap [4]
	The lightmap texture used with pureLight.
string	mapTo
	Used to map this material to the material name used by TSShape.
float	minnaertConstant [4]
	The Minnaert shading constant value. Must be greater than 0 to enable the effect.
filename	normalMap [4]
	The normal map texture. You can use the DXTnm format only when per-pixel specular highlights are disabled, or a specular map is in use.
filename	overlayMap [4]
	A secondary diffuse color texture map which will use the second texcoord of a mesh.
filename	overlayTex [4]
	For backwards compatibility.
float	parallaxScale [4]
	Enables parallax mapping and defines the scale factor for the parallax effect. Typically this value is less than 0.4 else the effect breaks down.
bool	pixelSpecular [4]
	This enables per-pixel specular highlights controlled by the alpha channel of the normal map texture. Note that if pixel specular is enabled the DXTnm format will not work with your normal map, unless you are also using a specular map.
bool	planarReflection
void	reload
	Reloads all material instances that use this material.
Point2F	rotPivotOffset [4]
	The piviot position in UV coordinates to center the rotation animation.
float	rotSpeed [4]
	The speed to rotate the texture in degrees per second when rotation animation is enabled.
Point2F	scrollDir [4]
	The scroll direction in UV space when scroll animation is enabled.
float	scrollSpeed [4]
	The speed to scroll the texture in UVs per second when scroll animation is enabled.
float	sequenceFramePerSec [4]
	The number of frames per second for frame based sequence animations if greater than zero.
float	sequenceSegmentSize [4]
	The size of each frame in UV units for sequence animations.
void	setAutoGenerated
	setAutoGenerated(bool isAutoGenerated): Set whether or not the Material is autogenerated.
ColorF	specular [4]
	The color of the specular highlight when not using a specularMap.
filename	specularMap [4]
	The specular map texture. The RGB channels of this texture provide a per-pixel replacement for the 'specular' parameter on the material. If this texture contains alpha information, the alpha channel of the texture will be used as the gloss map. This provides a per-pixel replacement for the 'specularPower' on the material.
float	specularPower [4]
	The intensity of the specular highlight when not using a specularMap.
bool	subSurface [4]
	Enables the subsurface scattering approximation.
ColorF	subSurfaceColor [4]
	The color used for the subsurface scattering approximation.
float	subSurfaceRolloff [4]
	The 0 to 1 rolloff factor used in the subsurface scattering approximation.
filename	toneMap [4]
	The tonemap texture used with pureLight.
bool	translucent
	If true this material is translucent blended.
MaterialBlendOp	translucentBlendOp
	The type of blend operation to use when the material is translucent.
bool	translucentZWrite
	If enabled and the material is translucent it will write into the depth buffer.
bool	useAnisotropic [4]
	Use anisotropic filtering for the textures of this stage.
bool	vertColor [4]
	If enabled, vertex colors are premultiplied with diffuse colors.
bool	vertLit [4]
	If true the vertex color is used for lighting.
float	waveAmp [4]
	The wave amplitude when wave animation is enabled.
float	waveFreq [4]
	The wave frequency when wave animation is enabled.
MaterialWaveType	waveType [4]
	The type of wave animation to perform when wave animation is enabled.
Behavioral

SFXTrack	customFootstepSound
	The sound to play when the player walks over the material. If this is set, it overrides footstepSoundId. This field is useful for directly assigning custom footstep sounds to materials without having to rely on the PlayerData sound assignment.
SFXTrack	customImpactSound
	The sound to play when the player impacts on the surface with a velocity equal or greater than PlayerData::groundImpactMinSpeed. If this is set, it overrides impactSoundId. This field is useful for directly assigning custom impact sounds to materials without having to rely on the PlayerData sound assignment.
ColorF	effectColor [2]
	If showDust is true, this is the set of colors to use for the ParticleData of the dust emitter.
int	footstepSoundId
	What sound to play from the PlayerData sound list when the player walks over the material. -1 (default) to not play any sound.
int	impactSoundId
	What sound to play from the PlayerData sound list when the player impacts on the surface with a velocity equal or greater than PlayerData::groundImpactMinSpeed.
bool	showDust
	Whether to emit dust particles from a shape moving over the material. This is, for example, used by vehicles or players to decide whether to show dust trails.
bool	showFootprints
	Whether to show player footprint decals on this material.

Detailed Description

A material in Torque 3D is a data structure that describes a surface.

It contains many different types of information for rendering properties. Torque 3D generates shaders from Material definitions. The shaders are compiled at runtime and output into the example/shaders directory. Any errors or warnings generated from compiling the procedurally generated shaders are output to the console as well as the output window in the Visual C IDE.

Example:

singleton Material(DECAL_scorch)
{
   baseTex[0] = "./scorch_decal.png";
   vertColor[ 0 ] = true;

   translucent = true;
   translucentBlendOp = None;
   translucentZWrite = true;
   alphaTest = true;
   alphaRef = 84;
};

See also:: Rendering; ShaderData

Member Data Documentation

int Material::alphaRef

The alpha reference value for alpha testing. Must be between 0 to 255.

See also:: alphaTest

bool Material::alphaTest

Enables alpha test when rendering the material.

See also:: alphaRef

MaterialAnimType Material::animFlags[4]

The types of animation to play on this material.

filename Material::baseTex[4]

For backwards compatibility.

See also:: diffuseMap

bool Material::bumpAtlas[4]

filename Material::bumpTex[4]

For backwards compatibility.

See also:: normalMap

bool Material::castShadows

If set to false the lighting system will not cast shadows from this material.

Point2I Material::cellIndex[4]

Point2I Material::cellLayout[4]

int Material::cellSize[4]

ColorF Material::colorMultiply[4]

For backwards compatibility.

See also:: diffuseColor

string Material::cubemap

The name of a CubemapData for environment mapping.

SFXTrack Material::customFootstepSound

The sound to play when the player walks over the material. If this is set, it overrides footstepSoundId. This field is useful for directly assigning custom footstep sounds to materials without having to rely on the PlayerData sound assignment.

Be aware that materials are client-side objects. This means that the SFXTracks assigned to materials must be client-side, too.

SFXTrack Material::customImpactSound

The sound to play when the player impacts on the surface with a velocity equal or greater than PlayerData::groundImpactMinSpeed. If this is set, it overrides impactSoundId. This field is useful for directly assigning custom impact sounds to materials without having to rely on the PlayerData sound assignment.

Be aware that materials are client-side objects. This means that the SFXTracks assigned to materials must be client-side, too.

filename Material::detailMap[4]

A typically greyscale detail texture additively blended into the material.

filename Material::detailNormalMap[4]

A second normal map texture applied at the detail scale. You can use the DXTnm format only when per-pixel specular highlights are disabled.

float Material::detailNormalMapStrength[4]

Used to scale the strength of the detail normal map when blended with the base normal map.

Point2F Material::detailScale[4]

The scale factor for the detail map.

filename Material::detailTex[4]

For backwards compatibility.

See also:: detailMap

ColorF Material::diffuseColor[4]

This color is multiplied against the diffuse texture color. If no diffuse texture is present this is the material color.

filename Material::diffuseMap[4]

The diffuse color texture map.

bool Material::doubleSided

Disables backface culling casing surfaces to be double sided. Note that the lighting on the backside will be a mirror of the front side of the surface.

void Material::dumpInstances

Dumps a formatted list of the currently allocated material instances for this material to the console.

bool Material::dynamicCubemap

Enables the material to use the dynamic cubemap from the ShapeBase object its applied to.

ColorF Material::effectColor[2]

If showDust is true, this is the set of colors to use for the ParticleData of the dust emitter.

See also:: ParticleData::colors

bool Material::emissive[4]

Enables emissive lighting for the material.

filename Material::envMap[4]

The name of an environment map cube map to apply to this material.

filename Material::envTex[4]

For backwards compatibility.

See also:: envMap

void Material::flush

Flushes all material instances that use this material.

int Material::footstepSoundId

What sound to play from the PlayerData sound list when the player walks over the material. -1 (default) to not play any sound.

The IDs are:

string Material::getAnimFlags

string Material::getFilename

Get filename of material.

bool Material::glow[4]

Enables rendering this material to the glow buffer.

int Material::impactSoundId

What sound to play from the PlayerData sound list when the player impacts on the surface with a velocity equal or greater than PlayerData::groundImpactMinSpeed.

For a list of IDs, see footstepSoundId

bool Material::isAutoGenerated

Returns true if this Material was automatically generated by MaterialList::mapMaterials().

filename Material::lightMap[4]

The lightmap texture used with pureLight.

string Material::mapTo

Used to map this material to the material name used by TSShape.

float Material::minnaertConstant[4]

The Minnaert shading constant value. Must be greater than 0 to enable the effect.

filename Material::normalMap[4]

The normal map texture. You can use the DXTnm format only when per-pixel specular highlights are disabled, or a specular map is in use.

filename Material::overlayMap[4]

A secondary diffuse color texture map which will use the second texcoord of a mesh.

filename Material::overlayTex[4]

For backwards compatibility.

See also:: overlayMap

float Material::parallaxScale[4]

Enables parallax mapping and defines the scale factor for the parallax effect. Typically this value is less than 0.4 else the effect breaks down.

bool Material::pixelSpecular[4]

This enables per-pixel specular highlights controlled by the alpha channel of the normal map texture. Note that if pixel specular is enabled the DXTnm format will not work with your normal map, unless you are also using a specular map.

bool Material::planarReflection

void Material::reload

Reloads all material instances that use this material.

Point2F Material::rotPivotOffset[4]

The piviot position in UV coordinates to center the rotation animation.

float Material::rotSpeed[4]

The speed to rotate the texture in degrees per second when rotation animation is enabled.

Point2F Material::scrollDir[4]

The scroll direction in UV space when scroll animation is enabled.

float Material::scrollSpeed[4]

The speed to scroll the texture in UVs per second when scroll animation is enabled.

float Material::sequenceFramePerSec[4]

The number of frames per second for frame based sequence animations if greater than zero.

float Material::sequenceSegmentSize[4]

The size of each frame in UV units for sequence animations.

void Material::setAutoGenerated

setAutoGenerated(bool isAutoGenerated): Set whether or not the Material is autogenerated.

bool Material::showDust

Whether to emit dust particles from a shape moving over the material. This is, for example, used by vehicles or players to decide whether to show dust trails.

bool Material::showFootprints

Whether to show player footprint decals on this material.

See also:: PlayerData::decalData

ColorF Material::specular[4]

The color of the specular highlight when not using a specularMap.

filename Material::specularMap[4]

The specular map texture. The RGB channels of this texture provide a per-pixel replacement for the 'specular' parameter on the material. If this texture contains alpha information, the alpha channel of the texture will be used as the gloss map. This provides a per-pixel replacement for the 'specularPower' on the material.

float Material::specularPower[4]

The intensity of the specular highlight when not using a specularMap.

bool Material::subSurface[4]

Enables the subsurface scattering approximation.

ColorF Material::subSurfaceColor[4]

The color used for the subsurface scattering approximation.

float Material::subSurfaceRolloff[4]

The 0 to 1 rolloff factor used in the subsurface scattering approximation.

filename Material::toneMap[4]

The tonemap texture used with pureLight.

bool Material::translucent

If true this material is translucent blended.