Cesium API - Primitive 中文文档

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 图元是否从每个光源投射或接收阴影。

示例：

// 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()
}));

参考：

• GeometryInstance
• Appearance
• ClassificationPrimitive
• GroundPrimitive

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

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

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

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

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

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

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

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

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

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

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

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

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

将图元（所有几何实例），从模型坐标系转换到世界坐标系的4*4矩阵。 当这为单位矩阵时，图元是在世界坐标系（即地球的WGS84坐标）中绘制的。 本地参考系可以通过提供一个不同的转换矩阵来使用，就像Transforms.eastNorthUpToFixedFrame返回的那样。

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

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

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

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

确定此图元是否从每个光源投射或接收阴影。

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

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

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

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

返回 GeometryInstance 的每个实例的可修改属性。

以属性格式表示的类型化数组；如果没有实例，则未定义类型。

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

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

false

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

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