CesiumJS

CesiumJS is licensed under the Apache License, Version 2.0.

Key terms for users:

• Permissions: You are granted a perpetual, worldwide, non-exclusive, royalty-free, and irrevocable copyright and patent license to use, modify, and distribute the software.
• Redistribution Requirements: If you redistribute the work or derivative works, you must:
  • Provide a copy of the license.
  • Include prominent notices in modified files stating that you changed them.
  • Retain all original copyright, patent, trademark, and attribution notices.
  • Include a readable copy of any NOTICE file present in the original distribution.
• Trademarks: This license does not grant permission to use the trade names, trademarks, or product names of the licensor, except for reasonable descriptions of the origin of the work.
• Disclaimer: The work is provided on an "AS IS" basis, without warranties of any kind.

Copyright 2011-2024 CesiumJS Contributors

                                 Apache License
                           Version 2.0, January 2004
                        http://www.apache.org/licenses/

Fabric is a JSON schema used in CesiumJS to describe materials for objects like polygons, polylines, ellipsoids, and sensors. Materials define the visual appearance of these objects, ranging from simple colors to complex procedural patterns or combined textures.

To apply a material, assign it to the object's material property. You can use the shorthand Cesium.Material.fromType(type) or provide a full Fabric JSON object via new Cesium.Material({ fabric: { ... } }).

Each material has uniforms—input parameters that can be set during creation or modified later to update the appearance dynamically.

// Using shorthand for a built-in material
polygon.material = Cesium.Material.fromType("Color");

// Using the full Fabric JSON schema
polygon.material = new Cesium.Material({
  fabric: {
    type: "Color",
  },
});

// Modifying a uniform after creation
polygon.material.uniforms.color = Cesium.Color.WHITE;

Varyings allow you to pass data from the vertex shader to the fragment shader. You must declare them in the CustomShader constructor using Cesium.VaryingType. Cesium will automatically handle the GLSL out and in declarations.

Supported Varying Types:

• FLOAT (float)
• VEC2 (vec2)
• VEC3 (vec3)
• VEC4 (vec4)
• MAT2 (mat2)
• MAT3 (mat3)
• MAT4 (mat4)

Workflow:

1. Declare the varying in the varyings object of the constructor.
2. Assign a value to the varying in vertexShaderText.
3. Access the varying in fragmentShaderText.

const customShader = new Cesium.CustomShader({
  varyings: {
    v_selectedColor: Cesium.VaryingType.VEC4,
  },
  vertexShaderText: `
    void vertexMain(VertexInput vsInput, inout czm_modelVertexOutput vsOutput) {
        float positiveX = step(0.0, vsOutput.positionMC.x);
        v_selectedColor = mix(
            vsInput.attributes.color_0,
            vsInput.attributes.color_1,
            vsOutput.positionMC.x
        );
    }
  `,
  fragmentShaderText: `
    void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) {
        material.diffuse = v_selectedColor.rgb;
    }
  `,
});

To ensure high performance in shaders, follow these best practices:

• Minimize Computation: Compute expensive values in JavaScript and pass them as uniforms, or compute them per-vertex and pass them as varyings, rather than re-computing them per-fragment.
• Use discard Sparingly: Using discard can disable early-z GPU optimizations.
• Avoid Branching: Conditional logic (if-else) can disrupt GPU parallelism.
  • Branching on a uniform (e.g., if (czm_orthographicIn3D == 1.0)) is generally acceptable as the value is consistent across threads.
  • For non-trivial logic, use czm_branchFreeTernary to avoid performance bottlenecks caused by branching.

Example: Replacing an if statement with czm_branchFreeTernary

Instead of:

if (sphericalLatLong.y >= czm_pi) {
  sphericalLatLong.y = sphericalLatLong.y - czm_twoPi;
}

Use:

sphericalLatLong.y = czm_branchFreeTernary(sphericalLatLong.y < czm_pi, sphericalLatLong.y, sphericalLatLong.y - czm_twoPi);

The materialInput variable is available in both components and source definitions. It provides geometric and texture coordinate data for the current fragment.

materialInput Fields

Usage Examples

Visualize st texture coordinates:

{
  components: {
    diffuse: "vec3(materialInput.st, 0.0)"
  }
}

Visualize the eye-coordinate normal:

{
  components: {
    diffuse: "materialInput.normalEC"
  }
}