首页 / Cesium / API 文档

Primitive

先看结论

几何体与外观的组合，一次提交给 GPU 绘制。相比 Entity 少了一层属性系统和逐帧求值，要素上万时是更合适的选择。

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

new Cesium.Primitive({ geometryInstances, appearance, asynchronous, allowPicking, compressVertices, interleave, releaseGeometryInstances })

构造参数

参数	类型	默认	说明
`geometryInstances`	GeometryInstance \| Array	必填	一个或多个几何实例，共用同一外观
`appearance`	Appearance	—	着色方式，如 `PerInstanceColorAppearance`、`MaterialAppearance`
`asynchronous`	boolean	true	在 Web Worker 里创建几何，避免阻塞主线程
`allowPicking`	boolean	true	是否允许 `scene.pick` 命中
`compressVertices`	boolean	true	压缩顶点属性，降低显存占用
`interleave`	boolean	false	顶点属性交叉存放，GPU 读取更连续
`vertexCacheOptimize`	boolean	false	重排顶点顺序提升缓存命中率
`releaseGeometryInstances`	boolean	true	上传完成后释放 CPU 端几何数据

常用成员

成员	类型	说明
`show`	boolean	显示开关，默认 true
`modelMatrix`	Matrix4	整体变换矩阵，改它可以移动、旋转整个图元
`ready`	boolean	几何是否已上传到 GPU
`readyPromise`	Promise	就绪后 resolve 自身，异步场景下用得上
`geometryInstances`	GeometryInstance \| Array	构造时传入的实例；释放后可能为 undefined
`appearance`	Appearance	外观对象，可运行时修改材质
`allowPicking`	boolean	关闭后拾取不到，可省一块颜色缓冲
`debugShowBoundingVolume`	boolean	画出包围球，排查裁剪错误时用

常用方法

方法	返回	说明
`getGeometryInstanceAttributes(id)`	object	取出某个实例可写的属性，如 `color`
`destroy()`	—	释放顶点缓冲；从集合移除后再调用
`isDestroyed()`	boolean	是否已销毁

示例

// 两个盒子，颜色写进实例属性，共用一份顶点数据
var instances = [0, 1].map(function (i) {
  return new Cesium.GeometryInstance({
    geometry: new Cesium.BoxGeometry({
      vertexFormat: Cesium.PerInstanceColorAppearance.VERTEX_FORMAT,
      maximum: new Cesium.Cartesian3(100, 100, 100)
    }),
    modelMatrix: Cesium.Transforms.eastNorthUpToFixedFrame(
      Cesium.Cartesian3.fromDegrees(116.391 + i * 0.002, 39.907, 50)
    ),
    attributes: {
      color: Cesium.ColorGeometryInstanceAttribute.fromColor(
        Cesium.Color.fromCssColorString(i ? '#e8b04b' : '#4aa3ff')
      )
    },
    id: 'box-' + i
  });
});

var primitive = viewer.scene.primitives.add(new Cesium.Primitive({
  geometryInstances: instances,
  appearance: new Cesium.PerInstanceColorAppearance({
    flat: true,
    translucent: false
  }),
  asynchronous: true
}));

// 就绪后可以单独改某个实例的颜色
primitive.readyPromise.then(function () {
  var attr = primitive.getGeometryInstanceAttributes('box-0');
  attr.color = Cesium.ColorGeometryInstanceAttribute.toValue(
    Cesium.Color.RED
  );
});

注意事项

一个 Primitive 共用一种 Appearance；不同材质要拆成多个 Primitive。
releaseGeometryInstances 默认为 true，之后 geometryInstances 会变成 undefined，需要留数据就先自行保存。
异步创建期间 ready 为 false，此时改 modelMatrix 仍有效，但不要依赖几何对象。
Primitive 不是 Entity，没有 position 属性，移动要改 modelMatrix。

引用本文

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