/cesiumjs-materials-shaders

name: cesiumjs-materials-shaders
description: "CesiumJS materials and post-processing — Material, Fabric JSON, MaterialAppearance, ImageBasedLighting, PostProcessStage, PostProcessStageLibrary, bloom, depth of field, ambient occlusion, FXAA, tonemapping, BlendingState. Use when defining Fabric materials for entities or primitives, configuring PBR image-based lighting, or adding screen-space post-processing effects."

CesiumJS Materials, Shaders & Post-Processing

Version baseline: CesiumJS 1.144 (August 2026). All imports use ES module style.

Material System (Fabric JSON)

`Material` defines surface appearance for **Primitives** through a JSON schema called Fabric. Materials compile to GLSL and are consumed by `MaterialAppearance` or `PolylineMaterialAppearance`.

While a material's image loads, CesiumJS renders a placeholder texture that defaults to white. Since 1.144 the static `Texture.defaultColor` changes that placeholder color to avoid white flashes during material construction. Note that the `Texture` class is runtime-public but absent from the published TypeScript definitions, so TypeScript callers need a cast.

Built-in Material Types

**Surface:** `Color` (color), `Image` (image, repeat), `DiffuseMap`, `AlphaMap`, `SpecularMap`, `EmissionMap` (image, channel(s), repeat), `BumpMap`, `NormalMap` (image, channel(s), strength, repeat).

**Patterns:** `Grid` (color, cellAlpha, lineCount, lineThickness), `Stripe` (evenColor, oddColor, repeat), `Checkerboard` (lightColor, darkColor, repeat), `Dot` (lightColor, darkColor, repeat).

**Effects:** `Water` (baseWaterColor, blendColor, normalMap, frequency, animationSpeed, amplitude), `RimLighting` (color, rimColor, width), `Fade` (fadeInColor, fadeOutColor, maximumDistance).

**Terrain:** `ElevationContour` (color, spacing, width), `ElevationRamp` (image, minimumHeight, maximumHeight).

**Polyline:** `PolylineArrow` (color), `PolylineDash` (color, gapColor, dashLength, dashPattern), `PolylineGlow` (color, glowPower, taperPower), `PolylineOutline` (color, outlineColor, outlineWidth).

Creating Materials

import { Material, Color, Cartesian2 } from "cesium";

// Shorthand with fromType (preferred for built-in types)
const colorMat = Material.fromType("Color", { color: new Color(1.0, 0.0, 0.0, 0.5) });

// Full Fabric notation
const gridMat = new Material({
  fabric: {
    type: "Grid",
    uniforms: { color: Color.GREEN, cellAlpha: 0.1, lineCount: new Cartesian2(8, 8) },
  },
});

// Async loading -- awaits textures before first frame, no flicker
const imageMat = await Material.fromTypeAsync("Image", { image: "./textures/facade.png" });

Fabric materials are for primitive appearances. Do not use non-existent entity constructors such as `WaterMaterialProperty`; for the built-in water material, create `Material.fromType("Water", ...)` and apply it through `MaterialAppearance` on a `Primitive`.

Custom Fabric with GLSL Source

Use `source` for inline GLSL. Uniforms declared in `uniforms` are available by name in the shader.

import { Material, Color } from "cesium";

const pulseMaterial = new Material({
  fabric: {
    uniforms: { color: Color.CYAN, speed: 2.0 },
    source: `czm_material czm_getMaterial(czm_materialInput materialInput) {
      czm_material material = czm_getDefaultMaterial(materialInput);
      float pulse = sin(czm_frameNumber * speed * 0.01) * 0.5 + 0.5;
      material.diffuse = color.rgb;
      material.alpha = color.a * pulse;
      return material;
    }`,
  },
  translucent: true,
});

Applying Materials to Primitives

import { Primitive, GeometryInstance, RectangleGeometry, Rectangle,
  MaterialAppearance, Material, Color, Cartesian2 } from "cesium";

viewer.scene.primitives.add(new Primitive({
  geometryInstances: new GeometryInstance({
    geometry: new RectangleGeometry({ rectangle: Rectangle.fromDegrees(-100, 30, -90, 40) }),
  }),
  appearance: new MaterialAppearance({
    material: Material.fromType("Checkerboard", {
      lightColor: Color.WHITE, darkColor: Color.BLACK, repeat: new Cartesian2(4, 4),
    }),
  }),
}));

Compositing Sub-Materials (Fabric `materials` + `components`)

import { Material, Color } from "cesium";

const compositeMat = new Material({ fabric: {
  materials: {
    gridMaterial: { type: "Grid" },
    colorMaterial: { type: "Color", uniforms: { color: Color.BLUE } },
  },
  components: {
    diffuse: "gridMaterial.diffuse + 0.2 * colorMaterial.diffuse",
    alpha: "min(gridMaterial.alpha, colorMaterial.alpha)",
  },
}});

CustomShader

`CustomShader` injects user GLSL into `Model`, `Cesium3DTileset`, and `VoxelPrimitive` rendering, with access to vertex attributes, feature IDs, and `EXT_structural_metadata`.

**For shader authoring — struct reference, metadata access, feature IDs, voxel subset, 1.139 breaking changes, and seven worked examples — see the `cesiumjs-custom-shader` skill.** This skill owns the `CustomShader` integration surface; the authoring depth lives there.

Minimal example:

import { CustomShader, Model } from "cesium";

const shader = new CustomShader({
  fragmentShaderText: `
    void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) {
      material.diffuse = vec3(1.0, 0.5, 0.0);
    }
  `,
});
const model = await Model.fromGltfAsync({ url: "./building.glb", customShader: shader });
viewer.scene.primitives.add(model);

ImageBasedLighting

Controls PBR image-based lighting for `Model` and `Cesium3DTileset`. `imageBasedLightingFactor` (Cartesian2) scales diffuse (x) and specular (y) from 0 to 1. Diffuse comes from `sphericalHarmonicCoefficients` (array of 9 Cartesian3, L0-L2). Specular comes from `specularEnvironmentMaps` (URL to KTX2 cube map).

import { ImageBasedLighting, Model, Cartesian2, Cartesian3 } from "cesium";

const coefficients = [ // 9 Cartesian3 values for L0..L2 bands
  new Cartesian3(0.35, 0.35, 0.38), new Cartesian3(0.11, 0.11, 0.11),
  new Ca