Primitive

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

图元（Primitive）表示场景中的几何图形。这个几何图形可以来自单个的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 将图元（所有几何实例），从模型坐标系转换到世界坐标系的4*4矩阵。
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 确定图元是异步创建（true）还是阻塞直到准备就绪。
debugShowBoundingVolume Boolean false optional 只是用来调试，是否显示图元的包围球。
shadows ShadowMode ShadowMode.DISABLED optional 图元是否从每个光源投射或接收阴影。
Examples:
// 1.画一个半透明，表面为棋盘图案的椭圆。
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. 用独特的颜色绘制不同的实例
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. 在主线程上创建几何图形。
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:

Members

readonlyallowPicking : Boolean
Scene/Primitive.js 359

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

appearance : Appearance
Scene/Primitive.js 170

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

readonlyasynchronous : Boolean
Scene/Primitive.js 372

确定图元是异步创建（true）还是阻塞直到准备就绪。
Default Value: true

readonlycompressVertices : Boolean
Scene/Primitive.js 385

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

cull : Boolean
Scene/Primitive.js 221

当true时，渲染器视锥和水平视点将根据图元的包围体来裁剪它们。 如果您手动裁剪图元，请将其设置为 false 可获得较小的性能提升。
Default Value: true

debugShowBoundingVolume : Boolean
Scene/Primitive.js 229

此属性仅用于调试；它既不用于生产，也不是最优的。

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

Default Value: false

depthFailAppearance : Appearance
Scene/Primitive.js 182

在深度测试失败时，用于给图元着色的Appearance。 每个几何实例都以相同的外观着色。 有些外观，如PerInstanceColorAppearance允许赋予每个实例唯一的值。

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

需要EXT_frag_depth WebGL扩展才能正确渲染。如果不支持扩展，可能人为添加（artifacts）。

Default Value: undefined

readonlygeometryInstances : Array.<GeometryInstance>|GeometryInstance
Scene/Primitive.js 162

这个图元渲染的几何实例，它有可能为undefined（当构造图元时，如果options.releaseGeometryInstances属性为true）。

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

Default Value: undefined

readonlyinterleave : Boolean
Scene/Primitive.js 333

当true时，几何顶点属性是交错的，这可以略微提高渲染性能，但增加了加载时间。
Default Value: false

modelMatrix : Matrix4
Scene/Primitive.js 198

将图元（所有几何实例），从模型坐标系转换到世界坐标系的4*4矩阵。 当这为单位矩阵时，图元是在世界坐标系（即地球的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);

readonlyready : Boolean
Scene/Primitive.js 397

确定图元是否完成并准备渲染。如果为true，在下一次调用Primitive#update时渲染图元。

readonlyreadyPromise : Promise.<Primitive>
Scene/Primitive.js 409

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

readonlyreleaseGeometryInstances : Boolean
Scene/Primitive.js 346

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

shadows : ShadowMode
Scene/Primitive.js 247

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

show : Boolean
Scene/Primitive.js 206

图元是否显示，这将影响到所有的几何图形。
Default Value: true

readonlyvertexCacheOptimize : Boolean
Scene/Primitive.js 320

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

Methods

destroy()
Scene/Primitive.js 2059

销毁此对象持有的WebGL资源。

一旦对象被销毁，它将不能在使用; 调用除isDestroyed之外的任何函数都会导致DeveloperError异常。 因此，将返回值（undefined）赋给对象，如示例所示。
Throws:
Example:
e = e && e.destroy();
See:

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

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

如果该对象没被销毁，返回false。

如果该对象已经被销毁，使用isDestroyed会触发 DeveloperError 异常。
Returns:
false
See:

update()
Scene/Primitive.js 1747

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

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

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