Material

Material

new

A Material defines surface appearance through a combination of diffuse, specular, normal, emission, and alpha components. These values are specified using a JSON schema called Fabric which gets parsed and assembled into glsl shader code behind-the-scenes. Check out the wiki page for more details on Fabric.

Base material types and their uniforms:

  • Color
    • color: rgba color object.
  • Image
    • image: path to image.
    • repeat: Object with x and y values specifying the number of times to repeat the image.
  • DiffuseMap
    • image: path to image.
    • channels: Three character string containing any combination of r, g, b, and a for selecting the desired image channels.
    • repeat: Object with x and y values specifying the number of times to repeat the image.
  • AlphaMap
    • image: path to image.
    • channel: One character string containing r, g, b, or a for selecting the desired image channel.
    • repeat: Object with x and y values specifying the number of times to repeat the image.
  • SpecularMap
    • image: path to image.
    • channel: One character string containing r, g, b, or a for selecting the desired image channel.
    • repeat: Object with x and y values specifying the number of times to repeat the image.
  • EmissionMap
    • image: path to image.
    • channels: Three character string containing any combination of r, g, b, and a for selecting the desired image channels.
    • repeat: Object with x and y values specifying the number of times to repeat the image.
  • BumpMap
    • image: path to image.
    • channel: One character string containing r, g, b, or a for selecting the desired image channel.
    • repeat: Object with x and y values specifying the number of times to repeat the image.
    • strength: Bump strength value between 0.0 and 1.0 where 0.0 is small bumps and 1.0 is large bumps.
  • NormalMap
    • image: path to image.
    • channels: Three character string containing any combination of r, g, b, and a for selecting the desired image channels.
    • repeat: Object with x and y values specifying the number of times to repeat the image.
    • strength: Bump strength value between 0.0 and 1.0 where 0.0 is small bumps and 1.0 is large bumps.
  • Reflection
    • cubeMap: Object with positiveX, negativeX, positiveY, negativeY, positiveZ, and negativeZ image paths.
    • channels: Three character string containing any combination of r, g, b, and a for selecting the desired image channels.
  • Refraction
    • cubeMap: Object with positiveX, negativeX, positiveY, negativeY, positiveZ, and negativeZ image paths.
    • channels: Three character string containing any combination of r, g, b, and a for selecting the desired image channels.
    • indexOfRefractionRatio: Number representing the refraction strength where 1.0 is the lowest and 0.0 is the highest.
  • Fresnel
    • reflection: Reflection Material.
    • refraction: Refraction Material.
  • Brick
    • brickColor: rgba color object for the brick color.
    • mortarColor: rgba color object for the mortar color.
    • brickSize: Number between 0.0 and 1.0 where 0.0 is many small bricks and 1.0 is one large brick.
    • brickPct: Number for the ratio of brick to mortar where 0.0 is all mortar and 1.0 is all brick.
    • brickRoughness: Number between 0.0 and 1.0 representing how rough the brick looks.
    • mortarRoughness: Number between 0.0 and 1.0 representing how rough the mortar looks.
  • Wood
    • lightWoodColor: rgba color object for the wood's base color.
    • darkWoodColor: rgba color object for the color of rings in the wood.
    • ringFrequency: Number for the frequency of rings in the wood.
    • noiseScale: Object with x and y values specifying the noisiness of the ring patterns in both directions.
  • Asphalt
    • asphaltColor: rgba color object for the asphalt's color.
    • bumpSize: Number for the size of the asphalt's bumps.
    • roughness: Number that controls how rough the asphalt looks.
  • Cement
    • cementColor: rgba color object for the cement's color.
    • grainScale: Number for the size of rock grains in the cement.
    • roughness: Number that controls how rough the cement looks.
  • Grass
    • grassColor: rgba color object for the grass' color.
    • dirtColor: rgba color object for the dirt's color.
    • patchiness: Number that controls the size of the color patches in the grass.
  • Grid
    • color: rgba color object for the whole material.
    • cellAlpha: Alpha value for the cells between grid lines. This will be combined with color.alpha.
    • lineCount: Object with x and y values specifying the number of columns and rows respectively.
    • lineThickness: Object with x and y values specifying the thickness of grid lines (in pixels where available).
  • Stripe
    • horizontal: Boolean that determines if the stripes are horizontal or vertical.
    • lightColor: rgba color object for the stripe's light alternating color.
    • darkColor: rgba color object for the stripe's dark alternating color.
    • offset: Number that controls the stripe offset from the edge.
    • repeat: Number that controls the total number of stripes, half light and half dark.
  • Checkerboard
    • lightColor: rgba color object for the checkerboard's light alternating color.
    • darkColor: rgba color object for the checkerboard's dark alternating color.
    • repeat: Object with x and y values specifying the number of columns and rows respectively.
  • Dot
    • lightColor: rgba color object for the dot color.
    • darkColor: rgba color object for the background color.
    • repeat: Object with x and y values specifying the number of columns and rows of dots respectively.
  • TieDye
    • lightColor: rgba color object for the light color.
    • darkColor: rgba color object for the dark color.
    • frequency: Number that controls the frequency of the pattern.
  • Facet
    • lightColor: rgba color object for the light color.
    • darkColor: rgba color object for the dark color.
    • frequency: Number that controls the frequency of the pattern.
  • Blob
    • lightColor: rgba color object for the light color.
    • darkColor: rgba color object for the dark color.
    • frequency: Number that controls the frequency of the pattern.
  • Water
    • baseWaterColor: rgba color object base color of the water.
    • blendColor: rgba color object used when blending from water to non-water areas.
    • specularMap: Single channel texture used to indicate areas of water.
    • normalMap: Normal map for water normal perturbation.
    • frequency: Number that controls the number of waves.
    • normalMap: Normal map for water normal perturbation.
    • animationSpeed: Number that controls the animations speed of the water.
    • amplitude: Number that controls the amplitude of water waves.
    • specularIntensity: Number that controls the intensity of specular reflections.
  • RimLighting
    • color: diffuse color and alpha.
    • rimColor: diffuse color and alpha of the rim.
    • width: Number that determines the rim's width.
  • Erosion
    • color: diffuse color and alpha.
    • time: Time of erosion. 1.0 is no erosion; 0.0 is fully eroded.
  • Fade
    • fadeInColor: diffuse color and alpha at time
    • fadeOutColor: diffuse color and alpha at maximumDistance from time
    • maximumDistance: Number between 0.0 and 1.0 where the fadeInColor becomes the fadeOutColor. A value of 0.0 gives the entire material a color of fadeOutColor and a value of 1.0 gives the the entire material a color of fadeInColor
    • repeat: true if the fade should wrap around the texture coodinates.
    • fadeDirection: Object with x and y values specifying if the fade should be in the x and y directions.
    • time: Object with x and y values between 0.0 and 1.0 of the fadeInColor position
  • PolylineArrow
    • color: diffuse color and alpha.
  • PolylineGlow
    • color: color and maximum alpha for the glow on the line.
    • glowPower: strength of the glow, as a percentage of the total line width (less than 1.0).
  • PolylineOutline
    • color: diffuse color and alpha for the interior of the line.
    • outlineColor: diffuse color and alpha for the outline.
    • outlineWidth: width of the outline in pixels.

Parameters:
Name Type Argument Default Description
description.context Context The context used to create textures if the material uses them.
description.strict Boolean <optional>
false Throws errors for issues that would normally be ignored, including unused uniforms or materials.
description.fabric Object The fabric JSON used to generate the material.
Throws:
  • DeveloperError : fabric: uniform has invalid type.
  • DeveloperError : fabric: uniforms and materials cannot share the same property.
  • DeveloperError : fabric: cannot have source and components in the same section.
  • DeveloperError : fabric: property name is not valid. It should be 'type', 'materials', 'uniforms', 'components', or 'source'.
  • DeveloperError : fabric: property name is not valid. It should be 'diffuse', 'specular', 'shininess', 'normal', 'emission', or 'alpha'.
  • DeveloperError : image: context is not defined.
  • DeveloperError : strict: shader source does not use string.
  • DeveloperError : strict: shader source does not use uniform.
  • DeveloperError : strict: shader source does not use material.
Example
// Create a color material with fromType:
polygon.material = Material.fromType(context, 'Color');
polygon.material.uniforms.color = {
    red : 1.0,
    green : 1.0,
    blue : 0.0
    alpha : 1.0
};

// Create the default material:
polygon.material = new Material();

// Create a color material with full Fabric notation:
polygon.material = new Material({
    context : context,
    fabric : {
        type : 'Color',
        uniforms : {
            color : {
                red : 1.0,
                green : 1.0,
                blue : 0.0,
                alpha : 1.0
            }
        }
    }
});
Demo:
See:
Source:

Members

:Object

Maps sub-material names to Material objects.

:String

The glsl shader source for this material.

:String

The material type. Can be an existing type or a new type. If no type is specified in fabric, type is a GUID.

:Object

Maps uniform names to their values.

Methods

Destroys the WebGL resources held by this object. Destroying an object allows for deterministic release of WebGL resources, instead of relying on the garbage collector to destroy this object.

Once an object is destroyed, it should not be used; calling any function other than isDestroyed will result in a DeveloperError exception. Therefore, assign the return value (undefined) to the object as done in the example.

Throws:
DeveloperError : This object was destroyed, i.e., destroy() was called.
Returns:
Example
material = material && material.destroy();
See:

Returns true if this object was destroyed; otherwise, false.

If this object was destroyed, it should not be used; calling any function other than isDestroyed will result in a DeveloperError exception.

Returns:
Boolean True if this object was destroyed; otherwise, false.
See:

<static>

Creates a new material using an existing material type.

Shorthand for: new Material({context : context, fabric : {type : type}});

Parameters:
Name Type Description
context Context The context used to create textures if the material uses them.
type String The base material type.
Throws:
DeveloperError : material with that type does not exist.
Returns:
Material New material object.
Example
var material = Material.fromType(context, 'Color');
material.uniforms.color = vec4(1.0, 0.0, 0.0, 1.0);
Documentation generated by JSDoc 3 on Mon Jun 03 2013 13:35:09 GMT-0400 (EDT)