Primitive

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

基元表示 Scene 中的几何体。 几何体可以来自单个 GeometryInstance (如下面的示例 1 所示)或实例数组，即使几何体来自不同的 几何类型，例如 RectangleGeometry 和 EllipsoidGeometry，如代码示例 2 所示。

基元将几何体实例与描述完整着色的 Appearance 组合在一起，包括 Material 和 RenderState 的 RenderState} 中。 粗略地说，geometry 实例定义了结构和位置， 和外观定义视觉特征。 解耦的几何图形和外观使我们能够混合 并匹配其中的大多数，并彼此独立地添加新的几何图形或外观。

将多个实例组合到一个基元中称为批处理，可显著提高静态数据的性能。 实例可以单独选取;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，则渲染器视锥体会剔除，而 horizon 会根据基元的边界体积剔除基元的命令。 如果您手动剔除基元，请将此项设置为 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 424

如果为 true，则每个几何体实例只能使用 Scene#pick 进行拾取。 如果为 false，则保存 GPU 内存。
Default Value: true

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

用于对此基元进行着色的 Appearance。每个几何体 实例以相同的外观进行着色。 一些外观，如 PerInstanceColorAppearance 允许为每个实例指定唯一性 性能。
Default Value: undefined

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

确定是否将在 Web Worker 上创建和批处理 geometry 实例。
Default Value: true

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

如果为 true，则几何顶点将被压缩，这将节省内存。
Default Value: true

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

如果为 true，则渲染器视锥体会剔除，Horizon 会剔除基元的命令 基于其边界体积。 将此设置为 false 可略微提高性能 如果要手动剔除基元。
Default Value: true

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

此属性仅用于调试;它不用于生产用途，也未进行优化。

为基元中的每个绘制命令绘制边界球体。

Default Value: false

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

Appearance 用于在深度测试失败时对此基元进行着色。每个几何体 实例以相同的外观进行着色。 一些外观，如 PerInstanceColorAppearance 允许为每个实例指定唯一性 性能。

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

需要 EXT_frag_depth WebGL 扩展才能正确呈现。如果该扩展不受支持，则 可能存在伪影。

Default Value: undefined

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

使用此基元渲染的几何体实例。 这可能会 如果 options.releaseGeometryInstances 为 undefined 在构造基元时为 true。

在渲染基元后更改此属性不起作用。

Default Value: undefined

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

确定几何体顶点属性是否交错，这可以略微提高渲染性能。
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 485

确定基元是否完整并准备好进行渲染。 如果此属性为 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 408

如果为 true，则基元不会保留对输入 geometryInstances 的引用以节省内存。
Default Value: true

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

确定此基本体是投射还是接收来自光源的阴影。
Default Value: ShadowMode.DISABLED

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

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

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

如果为 true，则几何顶点将针对前顶点着色器缓存和后顶点着色器缓存进行优化。
Default Value: true

Methods

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

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

一旦对象被销毁，就不应该使用它;调用 isDestroyed 将导致 DeveloperError 异常。 因此 将返回值 (undefined) 分配给对象，如示例中所示。

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

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

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

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

如果此对象已销毁，则不应使用;调用 isDestroyed 将导致 DeveloperError 异常。

Returns:
true，如果此对象被销毁;否则为 false。
See:

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

当 Viewer 或 CesiumWidget 将场景渲染到 获取渲染此基元所需的绘制命令。

请勿直接调用此函数。 这记录下来只是为了 列出渲染场景时可能传播的异常：

Throws:
  • DeveloperError : All instance geometries must have the same primitiveType.
  • DeveloperError : Appearance and material have a uniform with the same name.
  • DeveloperError : Primitive.modelMatrix is only supported in 3D mode.
  • RuntimeError : Vertex texture fetch support is required to render primitives with per-instance attributes. The maximum number of vertex texture image units must be greater than zero.
Need help? The fastest way to get answers is from the community and team on the Cesium Forum.
packages/engine
packages/widgets