Material - Cesium Documentation

# Material

#### new Material(options)

  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.
  - 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).
  - `lineOffset`: Object with x and y values specifying the offset of grid lines (range is 0 to 1).
  - Stripe
  - `horizontal`: Boolean that determines if the stripes are horizontal or vertical.
  - `evenColor`: rgba color object for the stripe's first color.
  - `oddColor`: rgba color object for the stripe's second color.
  - `offset`: Number that controls at which point into the pattern to begin drawing; with 0.0 being the beginning of the even color, 1.0 the beginning of the odd color, 2.0 being the even color again, and any multiple or fractional values being in between.
  - `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.
  - 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.
  - 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.

  Name | Type | Description
  --- | --- | ---

  `options`

  Object

  optional Object with the following properties:

  Name | Type | Default | Description
  --- | --- | --- | ---
  `strict` | Boolean | `false` | optional Throws errors for issues that would normally be ignored, including unused uniforms or materials.
  `translucent` | Boolean | function | `true` | optional When `true` or a function that returns `true`, the geometry with this material is expected to appear translucent.
  `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 : 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 = Cesium.Material.fromType('Color');
      polygon.material.uniforms.color = new Cesium.Color(1.0, 1.0, 0.0, 1.0);

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

      // Create a color material with full Fabric notation:
      polygon.material = new Cesium.Material({
          fabric : {
              type : 'Color',
              uniforms : {
                  color : new Cesium.Color(1.0, 1.0, 0.0, 1.0)
              }
          }
      });

  ##### Demo:

  - Cesium Sandcastle Materials Demo

  ##### See:

  - Fabric wiki page for a more detailed options of Fabric.
  Source: Scene/Material.js, line 261

### Members

#### staticreadonlyMaterial.AlphaMapType :String

  Gets the name of the alpha map material.
  Source: Scene/Material.js, line 1035

#### staticreadonlyMaterial.BumpMapType :String

  Gets the name of the bump map material.
  Source: Scene/Material.js, line 1098

#### staticreadonlyMaterial.CheckerboardType :String

  Gets the name of the checkerboard material.
  Source: Scene/Material.js, line 1186

#### staticreadonlyMaterial.ColorType :String

  Gets the name of the color material.
  Source: Scene/Material.js, line 971

#### staticMaterial.DefaultCubeMapId :String

  Gets or sets the default cube map texture uniform value.
  Source: Scene/Material.js, line 964

#### staticMaterial.DefaultImageId :String

  Gets or sets the default texture uniform value.
  Source: Scene/Material.js, line 958

#### staticreadonlyMaterial.DiffuseMapType :String

  Gets the name of the diffuce map material.
  Source: Scene/Material.js, line 1014

#### staticreadonlyMaterial.DotType :String

  Gets the name of the dot material.
  Source: Scene/Material.js, line 1208

#### staticreadonlyMaterial.EmissionMapType :String

  Gets the name of the emmision map material.
  Source: Scene/Material.js, line 1077

#### staticreadonlyMaterial.FadeType :String

  Gets the name of the fade material.
  Source: Scene/Material.js, line 1280

#### staticreadonlyMaterial.GridType :String

  Gets the name of the grid material.
  Source: Scene/Material.js, line 1138

#### staticreadonlyMaterial.ImageType :String

  Gets the name of the image material.
  Source: Scene/Material.js, line 993

#### staticreadonlyMaterial.NormalMapType :String

  Gets the name of the normal map material.
  Source: Scene/Material.js, line 1118

#### staticreadonlyMaterial.PolylineArrowType :String

  Gets the name of the polyline arrow material.
  Source: Scene/Material.js, line 1308

#### staticreadonlyMaterial.PolylineGlowType :String

  Gets the name of the polyline glow material.
  Source: Scene/Material.js, line 1325

#### staticreadonlyMaterial.PolylineOutlineType :String

  Gets the name of the polyline outline material.
  Source: Scene/Material.js, line 1343

#### staticreadonlyMaterial.RimLightingType :String

  Gets the name of the rim lighting material.
  Source: Scene/Material.js, line 1258

#### staticreadonlyMaterial.SpecularMapType :String

  Gets the name of the specular map material.
  Source: Scene/Material.js, line 1056

#### staticreadonlyMaterial.StripeType :String

  Gets the name of the stripe material.
  Source: Scene/Material.js, line 1162

#### staticreadonlyMaterial.WaterType :String

  Gets the name of the water material.
  Source: Scene/Material.js, line 1230

#### materials :Object

  Maps sub-material names to Material objects.
  Default Value: `undefined`
  Source: Scene/Material.js, line 281

#### shaderSource :String

  The glsl shader source for this material.
  Default Value: `undefined`
  Source: Scene/Material.js, line 274

#### translucent :Boolean|function

  When `true` or a function that returns `true`, the geometry is expected to appear translucent.
  Default Value: `undefined`
  Source: Scene/Material.js, line 297

#### type :String

  The material type. Can be an existing type or a new type. If no type is specified in fabric, type is a GUID.
  Default Value: `undefined`
  Source: Scene/Material.js, line 267

#### uniforms :Object

  Maps uniform names to their values.
  Default Value: `undefined`
  Source: Scene/Material.js, line 288

### Methods

#### staticMaterial.fromType(type, uniforms) → Material

  Creates a new material using an existing material type.
  Shorthand for: new Material({fabric : {type : type}});

  Name | Type | Description
  --- | --- | ---
  `type` | String | The base material type.
  `uniforms` | Object | optional Overrides for the default uniforms.

  ##### Returns:

  New material object.

  ##### Throws:

  - DeveloperError : material with that type does not exist.

  ##### Example:

      var material = Cesium.Material.fromType('Color', {
          color : new Cesium.Color(1.0, 0.0, 0.0, 1.0)
      });

  Source: Scene/Material.js, line 346

#### destroy() → undefined

  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.

  ##### Returns:

  ##### Throws:

  - DeveloperError : This object was destroyed, i.e., destroy() was called.

  ##### Example:

      material = material && material.destroy();

  ##### See:

  - Material#isDestroyed
  Source: Scene/Material.js, line 501

#### isDestroyed() → Boolean

  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:

  True if this object was destroyed; otherwise, false.

  ##### See:

  - Material#destroy
  Source: Scene/Material.js, line 480

#### isTranslucent()

  Gets whether or not this material is translucent.

  ##### Returns:

  `true` if this material is translucent, `false` otherwise.
  Source: Scene/Material.js, line 374