cesiumjs-custom-shader
CustomShader authoring — vertexShaderText and fragmentShaderText against VertexInput, FragmentInput, FeatureIds, Metadata, czm_modelMaterial. Use when reading EXT_mesh_features or EXT_structural_metadata property textures/tables, vertex displacement, or shading VoxelPrimitive.
CesiumGS · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add CesiumGS/cesiumjs-skills --skill cesiumjs-custom-shader技能说明
name: cesiumjs-custom-shader description: "CustomShader authoring — vertexShaderText and fragmentShaderText against VertexInput, FragmentInput, FeatureIds, Metadata, czm_modelMaterial. Use when reading EXT_mesh_features or EXT_structural_metadata property textures/tables, vertex displacement, or shading VoxelPrimitive."
CesiumJS CustomShader
Version baseline: CesiumJS 1.143. All imports use ES module style.
CustomShader injects user GLSL into the Model / Cesium3DTileset / VoxelPrimitive rendering pipeline. It exposes glTF attributes, feature IDs, and EXT_structural_metadata to per-vertex and per-fragment code, and returns values through the built-in czm_modelVertexOutput and czm_modelMaterial structs.
Use this skill for writing the shader body. Use:
cesiumjs-materials-shaders— for FabricMaterial,ImageBasedLighting,PostProcessStage(bloom, SSAO, FXAA, tonemapping).cesiumjs-3d-tiles— for declarative per-feature coloring viaCesium3DTileStyle, and forVoxelPrimitivesetup/configuration.cesiumjs-models-particles— forModel.fromGltfAsync, animations,ModelFeature.getProperty().
Out of scope
- Fabric
Materialfor entity polylines/polygons/walls — seecesiumjs-materials-shaders. PostProcessStagescreen-space effects — seecesiumjs-materials-shaders.ImageBasedLighting— seecesiumjs-materials-shaders.Cesium3DTileStyledeclarative JSON styling — seecesiumjs-3d-tiles. Do not combine with CustomShader on the same tileset.- Authoring
EXT_structural_metadata/EXT_mesh_featuresin glTF — tooling concern, not runtime.
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.0, 0.0);
material.alpha = 0.8;
}
`,
});
const model = await Model.fromGltfAsync({ url: "./aircraft.glb", customShader: shader });
viewer.scene.primitives.add(model);
Applying a CustomShader
Model — constructor option or mutable property:
const model = await Model.fromGltfAsync({ url, customShader });
model.customShader = newShader; // hot-swap
model.customShader = undefined; // clear
Cesium3DTileset — constructor option or mutable property. Only Model-backed tile content is affected (not native I3S or other formats):
const tileset = await Cesium3DTileset.fromUrl(url, { customShader });
tileset.customShader = newShader;
Per the
Cesium3DTileset.customShaderJSDoc: "Using custom shaders with aCesium3DTileStylemay lead to undefined behavior." The property is also marked@experimental— it uses 3D Tiles spec surface that is not final and may change without Cesium's standard deprecation policy.
VoxelPrimitive — fragment-only subset (see "VoxelPrimitive shader subset" below):
const voxelPrimitive = new VoxelPrimitive({ provider, customShader });
The engine calls customShader.update(frameState) automatically each frame. When finished with a CustomShader, call customShader.destroy() to release GPU texture resources owned by its TextureManager.
Constructor reference
new CustomShader({
mode, // CustomShaderMode — default MODIFY_MATERIAL
lightingModel, // LightingModel — if omitted, model's default is preserved
translucencyMode, // CustomShaderTranslucencyMode — default INHERIT
uniforms, // { [name]: { type: UniformType, value } } — default {}
varyings, // { [name]: VaryingType } — default {}
vertexShaderText, // string or undefined
fragmentShaderText, // string or undefined
});
Either vertexShaderText or fragmentShaderText is typically required. See REFERENCE.md for exhaustive enum values.
Shader function signatures
The runtime calls these from generated pipeline stages. Parameter names are part of the contract — renaming them breaks the shader.
void vertexMain(VertexInput vsInput, inout czm_modelVertexOutput vsOutput) { ... }
void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) { ... }
Uniforms
Declare uniforms with { type, value }. The type is a UniformType value; the JS value type must match (e.g. VEC3 → Cartesian3). Uniforms are accessible in GLSL by their declared name.
import { CustomShader, UniformType, TextureUniform, Cartesian3 } from "cesium";
const shader = new CustomShader({
uniforms: {
u_tint: { type: UniformType.VEC3, value: new Cartesian3(1.0, 0.5, 0.2) },
u_time: { type: UniformType.FLOAT, value: 0.0 },
u_detail: { type: UniformType.SAMPLER_2D, value: new TextureUniform({ url: "./detail.png", repeat: true }) },
},
fragmentShaderText: `
void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) {
vec3 d = texture(u_detail, fsInput.attributes.texCoord_0).rgb;
material.diffuse = mix(material.diffuse, u_tint, d.r + 0.1 * sin(u_time));
}
`,
});
// Update at runtime. For Cartesian/Matrix values, setUniform clones into existing storage.
shader.setUniform("u_time", performance.now() / 1000);
TextureUniform accepts either url (string or Resource) or typedArray + width + height — exactly one (constructor throws otherwise). Other options: repeat (default true), pixelFormat, pixelDatatype, minificationFilter, magnificationFilter, maximumAnisotropy.
SAMPLER_CUBE is declared on UniformType but rejected at construction — throws DeveloperError("CustomShader does not support samplerCube uniforms"). Only SAMPLER_2D is supported.
Varyings
Declared varyings are emitted as out <type> <name> in the vertex shader and in <type> <name> in the fragment shader. Write in vertex, read in fragment.
import { CustomShader, VaryingType } from "cesium";
const sh
阅读完整来源 ↗