Primitive

new Cesium.Primitive ( options )
Scene/Primitive.js 155

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

图元将几何实例与描述完整着色的 Appearance 组合在一起，包括 Material 和 RenderState 。粗略地说，几何实例定义了结构和位置，外观定义了视觉特征。解耦几何和外观允许我们混合和匹配它们中的大多数，并相互独立地添加新的几何或外观。

将多个实例组合成一个原语称为批处理，它显着提高了静态数据的性能。可以单独选择实例； Scene#pick 返回他们的 GeometryInstance#id 。使用 PerInstanceColorAppearance 类的每个实例外观，每个实例也可以具有唯一的颜色。

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

Name Type Description
options Object 具有以下属性的 可选 对象:
姓名 类型 默认 描述
geometryInstances 数组。< 几何实例 > | 几何实例 可选 要渲染的几何实例 - 或单个几何实例。
appearance 外貌 可选 用于渲染图元的外观。
depthFailAppearance 外貌 可选 当该图元未能通过深度测试时用于着色的外观。
show 布尔值 true 可选 确定是否显示此原语。
modelMatrix 矩阵4 Matrix4.IDENTITY 可选 将图元（所有几何实例）从模型转换为世界坐标的 4x4 转换矩阵。
vertexCacheOptimize 布尔值 false 可选 当 true 时，几何顶点针对顶点着色器前后缓存进行优化。
interleave 布尔值 false 可选 当 true 时，几何顶点属性是交错的，这可以稍微提高渲染性能但增加加载时间。
compressVertices 布尔值 true 可选 当 true 时，几何顶点被压缩，这将节省内存。
releaseGeometryInstances 布尔值 true 可选 当 true 时，基元不保留对输入 geometryInstances 的引用以节省内存。
allowPicking 布尔值 true 可选 当 true 时，每个几何实例只能通过 Scene#pick 来选择。当为 false 时，GPU 内存被保存。
cull 布尔值 true 可选 当 true 时，渲染器视锥体剔除和水平剔除基元的命令基于它们的边界体积。如果您手动剔除原语，请将其设置为 false 以获得较小的性能增益。
asynchronous 布尔值 true 可选 确定原语是异步创建还是阻塞直到准备好。
debugShowBoundingVolume 布尔值 false 可选 仅用于调试。确定是否显示此原语的命令的边界球。
shadows 阴影模式 ShadowMode.DISABLED 可选 确定此图元是否投射或接收来自光源的阴影。
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
Scene/Primitive.js 426

当为 true 时，每个几何实例只能通过 Scene#pick 进行拾取。当为 false 时，GPU 内存被保存。 *
Default Value: true

appearance : Appearance
Scene/Primitive.js 183

用于着色此图元的 Appearance 。每个几何实例都以相同的外观着色。某些外观，例如 PerInstanceColorAppearance 允许为每个实例赋予唯一的属性。
Default Value: undefined

readonly asynchronous : Boolean
Scene/Primitive.js 442

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

readonly compressVertices : Boolean
Scene/Primitive.js 458

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

cull : Boolean
Scene/Primitive.js 262

当为 true 时，渲染器视锥体剔除和地平线根据其边界体积剔除基元的命令。如果您手动剔除原语，请将其设置为 false 以获得较小的性能增益。
Default Value: true

debugShowBoundingVolume : Boolean
Scene/Primitive.js 274

该属性仅用于调试；它不是用于生产用途，也不是优化的。

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

Default Value: false

depthFailAppearance : Appearance
Scene/Primitive.js 206

未通过深度测试时用于着色此图元的 Appearance 。每个几何实例都以相同的外观着色。某些外观，例如 PerInstanceColorAppearance 允许为每个实例赋予唯一的属性。

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

需要 EXT_frag_depth WebGL 扩展才能正确呈现。如果不支持扩展，则可能存在工件。

Default Value: undefined

readonly geometryInstances : Array.< GeometryInstance >| GeometryInstance
Scene/Primitive.js 171

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

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

Default Value: undefined

readonly interleave : Boolean
Scene/Primitive.js 394

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

modelMatrix : Matrix4
Scene/Primitive.js 228

将图元（所有几何实例）从模型转换为世界坐标的 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
Scene/Primitive.js 474

确定图元是否完整并准备好渲染。如果此属性为真，则基元将在下次调用 Primitive#update 时呈现。

readonly readyPromise : Promise.< Primitive >
Scene/Primitive.js 486

获取当原语准备好渲染时解决的承诺。

readonly releaseGeometryInstances : Boolean
Scene/Primitive.js 410

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

shadows : ShadowMode
Scene/Primitive.js 304

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

show : Boolean
Scene/Primitive.js 241

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

readonly vertexCacheOptimize : Boolean
Scene/Primitive.js 378

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

Methods

destroy ()
Scene/Primitive.js 2484

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

一旦一个对象被销毁，它就不应该被使用；调用 isDestroyed 以外的任何函数都将导致 DeveloperError 异常。因此，如示例中所做的那样，将返回值 ( undefined ) 分配给对象。

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

getGeometryInstanceAttributes (id) → Object
Scene/Primitive.js 2395

返回 GeometryInstance 的可修改的每实例属性。
Name Type Description
id * GeometryInstance 的 ID。
Returns:
属性格式的类型化数组，如果没有具有 id 的实例，则为未定义。
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
Scene/Primitive.js 2463

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

如果这个对象被破坏了，它就不应该被使用；调用 isDestroyed 以外的任何函数都将导致 DeveloperError 异常。

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

update ()
Scene/Primitive.js 2096

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

不要直接调用这个函数。记录这只是为了列出渲染场景时可能传播的异常:

Throws:
  • DeveloperError :所有实例几何必须具有相同的primitiveType。
  • DeveloperError : 外观和材质有同名的制服。
  • DeveloperError : Primitive.modelMatrix 仅在 3D 模式下受支持。
  • RuntimeError :需要顶点纹理获取支持来渲染具有每个实例属性的图元。顶点纹理图像单元的最大数量必须大于零。