CustomShader

new Cesium.CustomShader(options)
engine/Source/Scene/Model/CustomShader.js 122

A user defined GLSL shader used with Model as well as Cesium3DTileset.

If texture uniforms are used, additional resource management must be done:

  • The update function must be called each frame. When a custom shader is passed to a Model or a Cesium3DTileset, this step is handled automaticaly
  • CustomShader#destroy must be called when the custom shader is no longer needed to clean up GPU resources properly. The application is responsible for calling this method.

See the Custom Shader Guide for more detailed documentation.

Name Type Description
options object An object with the following options
Name Type Default Description
mode CustomShaderMode CustomShaderMode.MODIFY_MATERIAL optional The custom shader mode, which determines how the custom shader code is inserted into the fragment shader.
lightingModel LightingModel optional The lighting model (e.g. PBR or unlit). If present, this overrides the default lighting for the model.
translucencyMode CustomShaderTranslucencyMode CustomShaderTranslucencyMode.INHERIT optional The translucency mode, which determines how the custom shader will be applied. If the value is CustomShaderTransulcencyMode.OPAQUE or CustomShaderTransulcencyMode.TRANSLUCENT, the custom shader will override settings from the model's material. If the value is CustomShaderTransulcencyMode.INHERIT, the custom shader will render as either opaque or translucent depending on the primitive's material settings.
uniforms Object.<string, UniformSpecifier> optional A dictionary for user-defined uniforms. The key is the uniform name that will appear in the GLSL code. The value is an object that describes the uniform type and initial value
varyings Object.<string, VaryingType> optional A dictionary for declaring additional GLSL varyings used in the shader. The key is the varying name that will appear in the GLSL code. The value is the data type of the varying. For each varying, the declaration will be added to the top of the shader automatically. The caller is responsible for assigning a value in the vertex shader and using the value in the fragment shader.
vertexShaderText string optional The custom vertex shader as a string of GLSL code. It must include a GLSL function called vertexMain. See the example for the expected signature. If not specified, the custom vertex shader step will be skipped in the computed vertex shader.
fragmentShaderText string optional The custom fragment shader as a string of GLSL code. It must include a GLSL function called fragmentMain. See the example for the expected signature. If not specified, the custom fragment shader step will be skipped in the computed fragment shader.
Example:
const customShader = new CustomShader({
  uniforms: {
    u_colorIndex: {
      type: Cesium.UniformType.FLOAT,
      value: 1.0
    },
    u_normalMap: {
      type: Cesium.UniformType.SAMPLER_2D,
      value: new Cesium.TextureUniform({
        url: "http://example.com/normal.png"
      })
    }
  },
  varyings: {
    v_selectedColor: Cesium.VaryingType.VEC3
  },
  vertexShaderText: `
  void vertexMain(VertexInput vsInput, inout czm_modelVertexOutput vsOutput) {
    v_selectedColor = mix(vsInput.attributes.color_0, vsInput.attributes.color_1, u_colorIndex);
    vsOutput.positionMC += 0.1 * vsInput.attributes.normal;
  }
  `,
  fragmentShaderText: `
  void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) {
    material.normal = texture(u_normalMap, fsInput.attributes.texCoord_0);
    material.diffuse = v_selectedColor;
  }
  `
});
Experimental

This feature is using part of the 3D Tiles spec that is not final and is subject to change without Cesium's standard deprecation policy.

Members

readonly fragmentShaderText : string
engine/Source/Scene/Model/CustomShader.js 169

The user-defined GLSL code for the fragment shader

readonly lightingModel : LightingModel
engine/Source/Scene/Model/CustomShader.js 140

The lighting model to use when using the custom shader. This is used by CustomShaderPipelineStage

readonly mode : CustomShaderMode
engine/Source/Scene/Model/CustomShader.js 132

A value determining how the custom shader interacts with the overall fragment shader. This is used by CustomShaderPipelineStage

readonly translucencyMode : CustomShaderTranslucencyMode
engine/Source/Scene/Model/CustomShader.js 181

The translucency mode, which determines how the custom shader will be applied. If the value is CustomShaderTransulcencyMode.OPAQUE or CustomShaderTransulcencyMode.TRANSLUCENT, the custom shader will override settings from the model's material. If the value isCustomShaderTransulcencyMode.INHERIT, the custom shader will render as either opaque or translucent depending on the primitive's material settings.
Default Value: CustomShaderTranslucencyMode.INHERIT

readonly uniforms : Object.<string, UniformSpecifier>
engine/Source/Scene/Model/CustomShader.js 147

Additional uniforms as declared by the user.

readonly varyings : Object.<string, VaryingType>
engine/Source/Scene/Model/CustomShader.js 155

Additional varyings as declared by the user. This is used by CustomShaderPipelineStage

readonly vertexShaderText : string
engine/Source/Scene/Model/CustomShader.js 162

The user-defined GLSL code for the vertex shader

Methods

setUniform(uniformName, value)
engine/Source/Scene/Model/CustomShader.js 410

Update the value of a uniform declared in the shader
Name Type Description
uniformName string The GLSL name of the uniform. This must match one of the uniforms declared in the constructor
value boolean | number | Cartesian2 | Cartesian3 | Cartesian4 | Matrix2 | Matrix3 | Matrix4 | string | Resource | TextureUniform The new value of the uniform.
Need help? The fastest way to get answers is from the community and team on the Cesium Forum.
packages/engine
packages/widgets