首页 / Cesium / API 文档

Appearance

先看结论

外观决定图元怎么被着色。基类 Appearance 要求自己写着色器，子类 MaterialAppearance 直接套用 Cesium 的材质系统。

最后验证 2026-11-03 · CesiumJS 1.121 · 更新 2026-10-29 · 引用本文

new Cesium.MaterialAppearance(options)

构造参数

参数	默认	说明
`material`	Color 材质	`Material` 实例，决定表面外观
`flat`	false	true 时不做光照计算，颜色只来自材质
`faceForward`	true	背面翻转法线，双面材质不会发黑
`translucent`	true	是否按半透明排序渲染
`vertexShaderSource`	内置	自定义顶点着色器，需实现 `czm_computePosition()`
`fragmentShaderSource`	内置	自定义片元着色器，需实现 `czm_getMaterial(materialInput)`
`renderState`	自动	覆盖深度测试、混合等渲染状态

属性

属性	说明
`material`	当前材质，可在运行时替换
`flat`	是否关闭光照
`faceForward`	是否翻转背面法线
`translucent`	是否半透明
`vertexShaderSource`	顶点着色器源码
`fragmentShaderSource`	片元着色器源码
`renderState`	渲染状态对象

方法

方法	返回	说明
`getFragmentShaderSource()`	String	拼接后的片元着色器
`getRenderState()`	Object	渲染状态
`isTranslucent()`	Boolean	是否按半透明处理

示例：材质外观

var appearance = new Cesium.MaterialAppearance({
  material: Cesium.Material.fromType('Stripe', {
    horizontal: false,
    repeat: 8,
    evenColor: Cesium.Color.WHITE,
    oddColor: Cesium.Color.fromCssColorString('#2f7cd6')
  }),
  flat: false,
  faceForward: true,
  translucent: false
});

var primitive = new Cesium.Primitive({
  geometryInstances: new Cesium.GeometryInstance({
    geometry: Cesium.PolygonGeometry.fromPositions({
      positions: Cesium.Cartesian3.fromDegreesArray([
        116.30, 39.86,
        116.46, 39.86,
        116.46, 39.99,
        116.30, 39.99
      ]),
      vertexFormat: Cesium.MaterialAppearance.VERTEX_FORMAT
    })
  }),
  appearance: appearance
});

viewer.scene.primitives.add(primitive);

三种常用外观的分工

外观	适用场景	顶点格式要求
`MaterialAppearance`	需要纹理、条纹、水波等材质	`MaterialAppearance.VERTEX_FORMAT`
`PerInstanceColorAppearance`	每个实例一种纯色，性能最好	`PerInstanceColorAppearance.VERTEX_FORMAT`
`PolylineColorAppearance`	逐顶点着色的折线	`PolylineColorAppearance.VERTEX_FORMAT`

自定义着色器的约定

直接继承 Appearance 时，顶点着色器必须提供 czm_computePosition() 返回裁剪空间坐标，片元着色器必须提供 czm_getMaterial(materialInput) 返回材质颜色。两者缺一，编译期就会报错，而错误只会出现在控制台，页面上表现为整块图元消失。

顶点格式要与着色器读取的属性对应：读取了 normal 却没有在几何里提供，法线会恒为零，光照结果全黑。flat: true 可以绕开这个问题。

材质数量和帧率直接相关。每个不同的 Material 实例都会生成独立着色器程序，成百上千个实例会让程序编译成为瓶颈。颜色差异用 PerInstanceColorAppearance，只有真正需要图案时才用材质。

引用本文

经纬志（2026）。《Appearance》。https://www.jingweizhi.com/cesium/api/appearance.html（访问日期 2026-11-03）。