Cesium快速入门25：自定义MaterialProperty

上一节课，我们能在 Primitive 里徒手写着色器；今天把“魔杖”伸回Entity——让它也用上完全自定义的材质。
思路一句话：Entity 只认MaterialProperty接口，我们手写一个类，把 Fabric + GLSL 塞进去，就能像官方材质一样随取随用。

一、MaterialProperty 接口长啥样？

官方把MaterialProperty当“抽象基类”，规定必须实现：

• getType()—— 返回材质字符串 ID；

• getValue(time, result)—— 每帧把最新 uniform 值写进 result；

• definitionChanged—— 事件对象，通知 Entity“我变了，请重绘”。

照猫画虎，自己写个类即可。

二、最小能跑的案例：CustomMaterialProperty

步骤：

1. 先在 Cesium 材质缓存里注册一个同名 Fabric；

2. 再在getValue里不停刷新 uniform；

3. Entity 里当普通材质用。

class CustomMaterialProperty { constructor() { // 1. 通知系统“我要变”的事件 this.definitionChanged = new Cesium.Event(); // 2. 把 Fabric 写进全局缓存，ID 叫 'CustomMaterial' Cesium.Material._materialCache.addMaterial('CustomMaterial', { fabric: { type: 'CustomMaterial', uniforms: { uTime: 0.0 // 初始值 }, source: ` czm_material czm_getMaterial(czm_materialInput materialInput) { czm_material mat = czm_getDefaultMaterial(materialInput); mat.diffuse = vec3(materialInput.st, uTime); // UV+时间当颜色 return mat; } ` } }); } // 3. 返回材质 ID getType() { return 'CustomMaterial'; } // 4. 每帧被 Entity 调用，把最新时间写回 uniform getValue(time, result) { result.uTime = (performance.now() / 1000) % 1; // 0~1 循环 return result; } }

代码写完后，当普通材质直接用：

const customMaterial = new CustomMaterialProperty(); viewer.entities.add({ name: 'Red translucent rectangle', rectangle: { coordinates: Cesium.Rectangle.fromDegrees(114.0, 23.4, 114.4, 23.6), extrudedHeight: 30000.0, material: customMaterial, // 自己的材质 }, });

刷新场景，矩形立刻带上“UV 彩条”，并且红色通道随时间流动——自定义成功！

三、想更平滑？交给 GSAP 去补间

performance.now()虽然简单，但节奏固定。
想要“呼吸”效果，可把 uniform 外包给 GSAP：

// 1. 先在构造函数里准备参数对象 this.params = { uTime: 0.0 }; gsap.to(this.params, { uTime: 1.0, duration: 2.0, repeat: -1, ease: 'linear' }); // 2. getValue 只负责“搬运” getValue(time, result) { result.uTime = this.params.uTime; return result; }

现在条纹会像扫描线一样来回走动，完全平滑。

四、常见坑提醒

• ID 必须对应：Fabric 的type/getType()/ 缓存 key 三处要完全一致；

• getValue里一定要return result，否则 Entity 拿不到新值；

• 想刷新画面就触发this.definitionChanged.raiseEvent(this)，Entity 才会重绘。

五、小结与展望

• Entity 自定义材质 = 实现MaterialProperty接口 + 注册同名 Fabric。

• 时间动画既能用performance.now()，也能让 GSAP 补间参数。

• 下一步：把“UV+时间”换成“距离+时间”，一个标准“雷达扫描圈”就呼之欲出了。