Primitive

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

一个原始对象表示 Scene 中的几何图形。几何图形可以来自单个 GeometryInstance （如下例 1 所示），也可以来自多个实例，即使几何图形来自不同的几何类型，例如 RectangleGeometry 和 EllipsoidGeometry，如代码示例 2 所示。

一个原始对象将几何实例与描述完整阴影的 Appearance 结合在一起，包括 Material 和 RenderState。 大致上，几何实例定义了结构和放置，外观定义了视觉特征。将几何和外观解耦允许我们混合和匹配大多数内容，并独立于彼此添加新的几何或外观。

将多个实例合并为一个原始对象被称为批处理，这显著提高了静态数据的性能。 实例可以被单独选择；Scene#pick 返回它们的 GeometryInstance#id。使用每实例外观，如 PerInstanceColorAppearance， 每个实例也可以具有唯一的颜色。

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

Name Type Description
options object optional 包含以下属性的对象：
Name Type Default Description
geometryInstances Array.<GeometryInstance> | GeometryInstance optional 要渲染的几何实例 - 或单个几何实例。
appearance Appearance optional 用于渲染原始对象的外观。
depthFailAppearance Appearance optional 当原始对象未通过深度测试时用于着色该原始对象的外观。
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 415

当 true 时，每个几何实例将只能通过 Scene#pick 进行选择。当 false 时，节省 GPU 内存。
Default Value: true

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

用于阴影此原始对象的 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 449

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

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

当 true 时，渲染器根据原始对象的包围体积进行视锥剔除和地平线剔除。 如果您手动剔除原始对象，可以将此设置为 false 以获得小的性能提升。
Default Value: true

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

此属性仅用于调试；不适合生产使用，也未进行优化。

绘制原始对象中每个绘制命令的包围球。

Default Value: false

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

当深度测试失败时用于阴影此原始对象的 Appearance。每个几何实例都使用相同的外观进行阴影处理。某些外观，例如 PerInstanceColorAppearance 允许为每个实例提供独特的属性。

当使用需要颜色属性的外观时，例如 PerInstanceColorAppearance，请为每个实例属性添加 depthFailColor。

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

Default Value: undefined

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

与此原始对象一起渲染的几何实例。如果在构造原始对象时 options.releaseGeometryInstances 为 true，则可能为 undefined。

在原始对象渲染后更改此属性没有效果。

Default Value: undefined

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

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

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

将原始对象（所有几何实例）从模型坐标转换到世界坐标的 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 399

当 true 时，原始对象不保留对输入 geometryInstances 的引用以节省内存。
Default Value: true

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

确定此原始对象是否从光源投射或接收阴影。
Default Value: ShadowMode.DISABLED

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

确定原始对象是否会被显示。此设置影响原始对象中的所有几何实例。
Default Value: true

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

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

Methods

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

销毁此对象持有的 WebGL 资源。销毁对象允许确定性地释放 WebGL 资源，而不是依赖于垃圾收集器销毁此对象。

一旦对象被销毁，就不应使用；调用除 isDestroyed 之外的任何功能将导致 DeveloperError 异常。因此， 将返回值 (undefined) 赋给对象，如示例中所示。

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

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

返回 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 2448

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

如果此对象已被销毁，则不应使用；调用除 isDestroyed 之外的任何功能将导致 DeveloperError 异常。

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

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

当 Viewer 或 CesiumWidget 渲染场景时被调用， 以获取渲染该原始对象所需的绘制命令。

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

Throws:
  • DeveloperError : 所有实例几何体必须具有相同的 primitiveType。
  • DeveloperError : Appearance 和材质具有相同名称的 uniform。
  • DeveloperError : Primitive.modelMatrix 仅在 3D 模式下支持。
  • RuntimeError : 渲染具有每实例属性的原始对象需要支持顶点纹理获取。顶点纹理图像单元的最大数量必须大于零。
需要帮助？获得答案的最快方法是来自社区和团队 Cesium Forum.
packages/engine
packages/widgets