Cesium快速入门15：图元Primitive创建图像物体

前面我们一直用 Entity------也就是"实体"------画矩形、椭球、走廊、圆柱、多边形、球体等等。Entity 把底层细节包得严严实实，一两行代码就能出效果。

可如果想再"底层"一点，自己捏顶点、配材质、写外观，那就得请出今天的主角：Primitive（图元）。

思路跟 Three.js 很像：先造几何体 → 再搞实例 → 再给外观 → 最后扔进场景。

步骤多了，但自由度直接拉满，后面甚至能自己写着色器做烟雾、流体等特效。

下面咱们把" Entity 画矩形"快速复习一遍，然后再用 Primitive 一模一样地复现它，每一步都拆开讲透。

一、Entity 版：两行代码画矩形

需求：在地球上贴两张"完全贴地"的矩形，红色半透明。

复制代码

// 1. 直接调实体接口
const redRect = viewer.entities.add({
  rectangle: {
    // 西南角 + 东北角 两个点定矩形
    coordinates: Cesium.Rectangle.fromDegrees(113.3, 23.0, 113.4, 23.2),
    material: Cesium.Color.RED.withAlpha(0.5)   // 红色半透明
  }
});

完事儿！简单，但黑盒。

二、Primitive 版：五步走，每一步都能改

我们把上面同样的矩形，用 Primitive 手敲一遍，看看底层到底干了啥。

【第 1 步】造几何体（Geometry）

告诉 Cesium：顶点怎么摆、要不要挤出高度、顶点格式用哪种。

复制代码

/* 1. 创建矩形几何体 */
const rectGeom = new Cesium.RectangleGeometry({
  rectangle: Cesium.Rectangle.fromDegrees(113.3, 23.0, 113.4, 23.2), // 贴地区域
  height: 0,                    // 离地 0 米------贴地
  extrudedHeight: 500,          // 向上挤出 500 米，形成"盒子"
  vertexFormat: Cesium.PerInstanceColorAppearance.VERTEX_FORMAT
  // 顶点格式：只保留"位置+颜色"属性，省内存，后面用实例颜色
});

小贴士

extrudedHeight 大于 height 时，矩形会被"挤"成盒子。
vertexFormat 决定每个顶点携带哪些属性（法线、UV、颜色等）。这里选"实例颜色"专用格式，省得带一堆用不到的数据。

【第 2 步】包成实例（GeometryInstance）

几何体是"模具"，实例才是"实物"。一个模具可以批量生产无数个实物，每个实物还能刷不同颜色。

复制代码

/* 2. 创建几何实例，并给它刷颜色 */
const instance = new Cesium.GeometryInstance({
  geometry: rectGeom,           // 上面做的模具
  attributes: {
    // 实例颜色属性：绿色半透明
    color: Cesium.ColorGeometryInstanceAttribute.fromColor(
             Cesium.Color.GREEN.withAlpha(0.5))
  }
});

注意：
Cesium.ColorGeometryInstanceAttribute.fromColor 是把普通颜色对象转成"实例属性"专用格式，别直接扔裸颜色进去。

【第 3 步】配外观（Appearance）

外观 = 材质 + 着色器 + 渲染状态。这里我们选"实例颜色外观"，意思是"颜色直接用实例里刷好的，不再贴纹理"。

复制代码

/* 3. 定义外观（材质） */
const appearance = new Cesium.PerInstanceColorAppearance({
  flat: true,      // 关闭光照，颜色纯纯的，不受太阳角度影响
  translucent: true // 允许半透明，方便看底层地形
});

【第 4 步】创建图元（Primitive）

把"实例"和"外观"合并成真正可渲染的"图元"。

复制代码

/* 4. 生成图元（类似 Three.js 的 Mesh） */
const rectPrimitive = new Cesium.Primitive({
  geometryInstances: instance,  // 实物
  appearance: appearance        // 外观
});

【第 5 步】扔进场景

复制代码

/* 5. 加入场景 */
viewer.scene.primitives.add(rectPrimitive);

三、小结：Entity vs Primitive

Entity：封装厚，代码少，适合快速出活。
Primitive：步骤多，粒度高，适合"想怎么画就怎么画"------顶点、索引、着色器、渲染状态全由你定。

今天先开个头，后面我们拿 Primitive 写自定义着色器，做烟雾、水流、建筑生长动画，再慢慢感受它的威力。