Primitive

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

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

基本体将几何实例与描述完整阴影的 Appearance 组合在一起，包括 材料 和 RenderState 。大致而言，几何实例定义了结构和位置，外观定义了视觉特征。去耦几何形状和外观使我们能够混合并匹配其中的大多数，并彼此独立地添加新的几何形状或外观。

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

几何 可以在网络工作者或主线程上创建和批处理。前两个例子显示将通过使用几何描述在Web工作者上创建的几何。第三个例子显示了如何通过显式调用 createGeometry 方法在主线程上创建几何的方法。

Name Type Description
options Object optional Object with the following properties:
Name Type Default Description
geometryInstances Array.< GeometryInstance > | GeometryInstance 可选 要渲染的几何实例-或单个几何实例。
appearance Appearance 可选 用于渲染图元的外观。
depthFailAppearance Appearance 可选 深度测试失败时，用于使该图元着色的外观。
show Boolean true 可选 确定是否将显示此原语。
modelMatrix Matrix4 Matrix4.IDENTITY 可选 4x4转换矩阵，用于将图元（所有几何实例）从模型坐标转换为世界坐标。
vertexCacheOptimize Boolean false 可选 如果为 true ，则为顶点着色器之前和之后的缓存优化几何顶点。
interleave Boolean false 可选 当 true 时，将交错几何图形顶点属性，这可以稍微改善渲染性能，但会增加加载时间。
compressVertices Boolean true 可选 当 true 时，将压缩几何顶点，这将节省内存。
releaseGeometryInstances Boolean true 可选 如果为 true ，则该原语不保留对输入的 geometryInstances 的引用以节省内存。
allowPicking Boolean true 可选 如果为 true ，则只能使用 Scene＃pick 来拾取每个几何实例。如果 false ，则保存GPU内存。
cull Boolean true 可选 如果为 true ，则渲染器视锥和水平视点将根据图元的边界体积来选择它们。如果您手动剔除原语，请将其设置为 false 可获得较小的性能提升。
asynchronous Boolean true 可选 确定基元是异步创建还是阻塞直到准备就绪。
debugShowBoundingVolume Boolean false 可选 仅用于调试。确定是否显示此图元命令的边界球。
shadows ShadowMode ShadowMode.DISABLED 可选 确定此图元是否投射或接收来自每个光源的阴影。
Examples: 
// 1. Draw a translucent ellipse on the surface with a checkerboard pattern
var 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
var 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)
  }
});
var 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()
}));
See:
翻译by:http://cesium.xin

Members

readonly allowPicking : Boolean
Scene/Primitive.js 459

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

appearance : Appearance
Scene/Primitive.js 230

外观 用于为该原语着色。每个几何实例以相同的外观着色。一些外观，例如 PerInstanceColorAppearance 允许给每个实例唯一属性。
Default Value: undefined

readonly asynchronous : Boolean
Scene/Primitive.js 475

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

readonly compressVertices : Boolean
Scene/Primitive.js 491

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

cull : Boolean
Scene/Primitive.js 304

如果为 true ，则渲染器视锥体会剔除视域，而horizo​​n会剔除基本体的命令根据它们的边界体积。将此设置为 false 可获得较小的性能提升如果要手动剔除原始图元。
Default Value: true

debugShowBoundingVolume : Boolean
Scene/Primitive.js 316

此属性仅用于调试。它不是用于生产用途，也不是经过优化的。

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

Default Value: false

depthFailAppearance : Appearance
Scene/Primitive.js 253

Appearance 用于在深度测试失败时为其着色。每个几何实例以相同的外观着色。一些外观，例如 PerInstanceColorAppearance 允许给每个实例唯一属性。

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

需要EXT_frag_depth WebGL扩展才能正确呈现。如果不支持扩展，可能有文物。

Default Value: undefined

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

用该图元渲染的几何实例。这可能如果 options.releaseGeometryInstances 为 undefined 构造基元时为 true 。

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

Default Value: undefined

readonly interleave : Boolean
Scene/Primitive.js 427

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

modelMatrix : Matrix4
Scene/Primitive.js 275

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

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

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

readonly ready : Boolean
Scene/Primitive.js 507

确定图元是否完整并且可以渲染。如果此属性是true，则下一次 Primitive＃update 时将渲染图元。叫做。

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

获取一个承诺，该承诺在准备好渲染图元时解析。

readonly releaseGeometryInstances : Boolean
Scene/Primitive.js 443

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

shadows : ShadowMode
Scene/Primitive.js 336

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

show : Boolean
Scene/Primitive.js 286

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

readonly vertexCacheOptimize : Boolean
Scene/Primitive.js 411

如果为 true ，则为顶点着色器之前和之后的缓存优化几何顶点。
Default Value: true

Methods

destroy ()
Scene/Primitive.js 2179

销毁此对象拥有的WebGL资源。销毁对象可以确定性释放WebGL资源，而不是依靠垃圾回收器来破坏此对象。

一旦物体被破坏，就不应使用。调用除 isDestroyed 将导致 DeveloperError 异常。因此，如示例中所述，将返回值（ undefined ）分配给对象。

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

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

返回 GeometryInstance 的每个实例的可修改属性。
Name Type Description
id * GeometryInstance 的ID。
Returns:
以属性格式表示的类型化数组；如果没有实例，则未定义类型。
Throws:
  • DeveloperError :必须在调用getGeometryInstanceAttributes之前调用update。
Example: 
var 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 2158

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

如果该对象被破坏，则不应使用。调用除 isDestroyed 将导致 DeveloperError 异常。

Returns:
真正 该物体是否被破坏；除此以外， 假 。
See:

update ()
Scene/Primitive.js 1861

在 Viewer 或 CesiumWidget 渲染场景时调用至获取渲染该图元所需的绘制命令。

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

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