Primitive

new Cesium.Primitive(options)
engine/Source/Scene/Primitive.js 154

图元表示 Scene 中的几何。几何可以来自单个 GeometryInstance （如下面的示例 1），也可以来自一组实例，即使这些几何来自不同的 几何类型，例如 RectangleGeometry 和 EllipsoidGeometry（如代码示例 2 所示）。

图元将几何体实例与描述完整着色的 Appearance 结合在一起，包括 Material 和 RenderState。粗略地说，几何体实例定义了结构与位置， 而 appearance 定义了视觉特征。将几何与 appearance 解耦，使我们可以混用 大多数几何与 appearance，并独立地添加新的几何或 appearance。

将多个实例合并到一个图元中称为批处理（batching），可显著提升静态数据的性能。 实例可以被单独拾取；Scene#pick 会返回它们的 GeometryInstance#id。使用 PerInstanceColorAppearance 等逐实例 appearance，每个实例还可以拥有唯一的颜色。

Geometry 可以在 Web Worker 或主线程上创建并批处理。前两个示例 展示了如何通过将几何的描述在 Web Worker 上创建几何。第三个示例 展示了如何通过显式调用 createGeometry 方法在主线程上创建几何。

Name Type Description
options object optional Object with the following properties:
Name Type Default Description
geometryInstances Array.<GeometryInstance> | GeometryInstance optional 要渲染的几何体实例——或单个几何体实例。
appearance Appearance optional 用于渲染图元的 appearance。
depthFailAppearance Appearance optional 当图元未通过深度测试时，用于为其着色的 appearance。
show boolean true optional 确定是否显示此图元。
modelMatrix Matrix4 Matrix4.IDENTITY optional 将图元（所有几何体实例）从模型坐标转换为世界坐标的 4x4 变换矩阵。
vertexCacheOptimize boolean false optional 当 true 时，几何体顶点会针对顶点着色器前后缓存进行优化。
interleave boolean false optional 当 true 时，几何体顶点属性会交错排列，这可以略微提升渲染性能，但会增加加载时间。
compressVertices boolean true optional 当 true 时，几何体顶点会被压缩以节省内存。
releaseGeometryInstances boolean true optional 当 true 时，为节省内存，图元不会保留对输入 geometryInstances 的引用。
allowPicking boolean true optional 当 true 时，每个几何体实例只能使用 Scene#pick 进行拾取。当 false 时，可节省 GPU 内存。
cull boolean true optional 当 true 时，渲染器会根据图元命令的包围体进行视锥剔除和地平线剔除。如果你手动剔除图元，可将其设为 false 以获得少量性能提升。
asynchronous boolean true optional 确定图元是异步创建还是在准备就绪前阻塞。
debugShowBoundingVolume boolean false optional 仅用于调试。确定是否显示此图元命令的包围球。
shadows ShadowMode ShadowMode.DISABLED optional 确定此图元是否投射或接收来自光源的阴影。
Examples:
// 1. Draw a translucent ellipse on the surface with a checkerboard pattern
const instance = new Cesium.GeometryInstance({
  geometry : new Cesium.EllipseGeometry({
      center : Cesium.Cartesian3.fromDegrees(-100.0, 20.0),
      semiMinorAxis : 500000.0,
      semiMajorAxis : 1000000.0,
      rotation : Cesium.Math.PI_OVER_FOUR,
      vertexFormat : Cesium.VertexFormat.POSITION_AND_ST
  }),
  id : 'object returned when this instance is picked and to get/set per-instance attributes'
});
scene.primitives.add(new Cesium.Primitive({
  geometryInstances : instance,
  appearance : new Cesium.EllipsoidSurfaceAppearance({
    material : Cesium.Material.fromType('Checkerboard')
  })
}));
// 2. Draw different instances each with a unique color
const rectangleInstance = new Cesium.GeometryInstance({
  geometry : new Cesium.RectangleGeometry({
    rectangle : Cesium.Rectangle.fromDegrees(-140.0, 30.0, -100.0, 40.0),
    vertexFormat : Cesium.PerInstanceColorAppearance.VERTEX_FORMAT
  }),
  id : 'rectangle',
  attributes : {
    color : new Cesium.ColorGeometryInstanceAttribute(0.0, 1.0, 1.0, 0.5)
  }
});
const ellipsoidInstance = new Cesium.GeometryInstance({
  geometry : new Cesium.EllipsoidGeometry({
    radii : new Cesium.Cartesian3(500000.0, 500000.0, 1000000.0),
    vertexFormat : Cesium.VertexFormat.POSITION_AND_NORMAL
  }),
  modelMatrix : Cesium.Matrix4.multiplyByTranslation(Cesium.Transforms.eastNorthUpToFixedFrame(
    Cesium.Cartesian3.fromDegrees(-95.59777, 40.03883)), new Cesium.Cartesian3(0.0, 0.0, 500000.0), new Cesium.Matrix4()),
  id : 'ellipsoid',
  attributes : {
    color : Cesium.ColorGeometryInstanceAttribute.fromColor(Cesium.Color.AQUA)
  }
});
scene.primitives.add(new Cesium.Primitive({
  geometryInstances : [rectangleInstance, ellipsoidInstance],
  appearance : new Cesium.PerInstanceColorAppearance()
}));
// 3. Create the geometry on the main thread.
scene.primitives.add(new Cesium.Primitive({
  geometryInstances : new Cesium.GeometryInstance({
    geometry : Cesium.EllipsoidGeometry.createGeometry(new Cesium.EllipsoidGeometry({
      radii : new Cesium.Cartesian3(500000.0, 500000.0, 1000000.0),
      vertexFormat : Cesium.VertexFormat.POSITION_AND_NORMAL
    })),
    modelMatrix : Cesium.Matrix4.multiplyByTranslation(Cesium.Transforms.eastNorthUpToFixedFrame(
      Cesium.Cartesian3.fromDegrees(-95.59777, 40.03883)), new Cesium.Cartesian3(0.0, 0.0, 500000.0), new Cesium.Matrix4()),
    id : 'ellipsoid',
    attributes : {
      color : Cesium.ColorGeometryInstanceAttribute.fromColor(Cesium.Color.AQUA)
    }
  }),
  appearance : new Cesium.PerInstanceColorAppearance(),
  asynchronous : false
}));
See:

Members

readonly allowPicking : boolean
engine/Source/Scene/Primitive.js 416

当 true 时，每个几何体实例只能使用 Scene#pick 进行拾取。当 false 时，可节省 GPU 内存。 *
Default Value: true

appearance : Appearance
engine/Source/Scene/Primitive.js 182

用于为此图元着色的 Appearance。每个几何体 实例都使用相同的 appearance 着色。某些 appearance（例如 PerInstanceColorAppearance）允许为每个实例指定唯一的 属性。
Default Value: undefined

readonly asynchronous : boolean
engine/Source/Scene/Primitive.js 432

确定几何体实例是否在 Web Worker 上创建并批处理。
Default Value: true

readonly compressVertices : boolean
engine/Source/Scene/Primitive.js 448

当 true 时，几何体顶点会被压缩以节省内存。
Default Value: true

cull : boolean
engine/Source/Scene/Primitive.js 256

当 true 时，渲染器会根据图元命令的包围体进行视锥剔除和地平线剔除。 将其设为 false 可获得少量性能提升 （如果你手动剔除图元）。
Default Value: true

debugShowBoundingVolume : boolean
engine/Source/Scene/Primitive.js 268

此属性仅用于调试；它不用于生产环境，也未经过优化。

为图元中的每个绘制命令绘制包围球。

Default Value: false

depthFailAppearance : Appearance
engine/Source/Scene/Primitive.js 205

当图元未通过深度测试时，用于为其着色的 Appearance。每个几何体 实例都使用相同的 appearance 着色。某些 appearance（例如 PerInstanceColorAppearance）允许为每个实例指定唯一的 属性。

使用需要颜色属性的 appearance（如 PerInstanceColorAppearance）时， 请改用 depthFailColor 逐实例属性。

需要 EXT_frag_depth WebGL 扩展才能正确渲染。如果不支持该扩展， 可能会出现伪影。

Default Value: undefined

readonly geometryInstances : Array.<GeometryInstance>|GeometryInstance
engine/Source/Scene/Primitive.js 170

使用此图元渲染的几何体实例。如果 构造图元时将 options.releaseGeometryInstances 设为 true， 则可能为 undefined。

在图元渲染后更改此属性无效。

Default Value: undefined

readonly interleave : boolean
engine/Source/Scene/Primitive.js 384

确定几何体顶点属性是否交错排列，这可以略微提升渲染性能。
Default Value: false

modelMatrix : Matrix4
engine/Source/Scene/Primitive.js 227

将图元（所有几何体实例）从模型坐标转换为世界坐标的 4x4 变换矩阵。 当其为单位矩阵时，图元在世界坐标（即地球的 WGS84 坐标）中绘制。 通过提供不同的变换矩阵（例如 Transforms.eastNorthUpToFixedFrame 返回的矩阵）可使用局部参考系。

此属性仅在 3D 模式下受支持。

Default Value: Matrix4.IDENTITY
Example:
const origin = Cesium.Cartesian3.fromDegrees(-95.0, 40.0, 200000.0);
p.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(origin);

readonly ready : boolean
engine/Source/Scene/Primitive.js 477

确定图元是否已构建完成并可以渲染。如果此属性为 true，则下次调用 Primitive#update 时会渲染该图元。
Example:
// Wait for a primitive to become ready before accessing attributes
const removeListener = scene.postRender.addEventListener(() => {
  if (!frustumPrimitive.ready) {
    return;
  }

  const attributes = primitive.getGeometryInstanceAttributes('an id');
  attributes.color = Cesium.ColorGeometryInstanceAttribute.toValue(Cesium.Color.AQUA);

  removeListener();
});

readonly releaseGeometryInstances : boolean
engine/Source/Scene/Primitive.js 400

当 true 时，为节省内存，图元不会保留对输入 geometryInstances 的引用。
Default Value: true

shadows : ShadowMode
engine/Source/Scene/Primitive.js 295

确定此图元是否投射或接收来自光源的阴影。
Default Value: ShadowMode.DISABLED

show : boolean
engine/Source/Scene/Primitive.js 238

确定是否显示此图元。这会影响图元中所有的几何体 实例。
Default Value: true

readonly vertexCacheOptimize : boolean
engine/Source/Scene/Primitive.js 368

当 true 时，几何体顶点会针对顶点着色器前后缓存进行优化。
Default Value: true

Methods

destroy()
engine/Source/Scene/Primitive.js 2456

销毁此对象持有的 WebGL 资源。销毁对象可以实现对 WebGL 资源的确定性释放，而不必依赖垃圾回收器来销毁此对象。

对象一旦被销毁就不应再使用；调用 isDestroyed 之外的任何函数 都会抛出 DeveloperError 异常。因此， 应像示例中那样将返回值（undefined）赋给该对象。

Throws:
Example:
e = e && e.destroy();
See:

getGeometryInstanceAttributes(id) → object
engine/Source/Scene/Primitive.js 2367

返回 GeometryInstance 的可修改逐实例属性。
Name Type Description
id * GeometryInstance 的 id。
Returns:
属性格式中的类型化数组；如果没有具有该 id 的实例，则为 undefined。
Throws:
  • DeveloperError : 在调用 getGeometryInstanceAttributes 之前必须先调用 update。
Example:
const attributes = primitive.getGeometryInstanceAttributes('an id');
attributes.color = Cesium.ColorGeometryInstanceAttribute.toValue(Cesium.Color.AQUA);
attributes.show = Cesium.ShowGeometryInstanceAttribute.toValue(true);
attributes.distanceDisplayCondition = Cesium.DistanceDisplayConditionGeometryInstanceAttribute.toValue(100.0, 10000.0);
attributes.offset = Cesium.OffsetGeometryInstanceAttribute.toValue(Cartesian3.IDENTITY);

isDestroyed() → boolean
engine/Source/Scene/Primitive.js 2435

如果此对象已被销毁则返回 true；否则返回 false。

如果此对象已被销毁，则不应再使用它；调用 isDestroyed 之外的任何函数 都会抛出 DeveloperError 异常。

Returns:
true 表示此对象已被销毁；否则为 false。
See:

update()
engine/Source/Scene/Primitive.js 2079

当 Viewer 或 CesiumWidget 渲染场景以获取 渲染此图元所需的绘制命令时调用。

不要直接调用此函数。此处仅记录文档，以 列出渲染场景时可能传播的异常：

Throws:
  • DeveloperError : 所有实例几何必须拥有相同的 primitiveType。
  • DeveloperError : Appearance 和 material 拥有同名的 uniform。
  • DeveloperError : Primitive.modelMatrix 仅在 3D 模式下受支持。
  • RuntimeError : 渲染具有逐实例属性的图元需要顶点纹理获取（vertex texture fetch）支持。顶点纹理图像单元的最大数量必须大于零。
需要帮助？获取答案的最快方式是在 Cesium 论坛 上向社区和团队提问。
CtrlK
packages/engine
packages/widgets