Primitive

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

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

A primitive combines geometry instances with an Appearance that describes the full shading, including Material and RenderState. Roughly, the geometry instance defines the structure and placement, and the appearance defines the visual characteristics. Decoupling geometry and appearance allows us to mix and match most of them and add a new geometry or appearance independently of each other.

Combining multiple instances into one primitive is called batching, and significantly improves performance for static data. Instances can be individually picked; Scene#pick returns their GeometryInstance#id. Using per-instance appearances like PerInstanceColorAppearance, each instance can also have a unique color.

Geometry can either be created and batched on a web worker or the main thread. The first two examples show geometry that will be created on a web worker by using the descriptions of the geometry. The third example shows how to create the geometry on the main thread by explicitly calling the createGeometry method.

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 61166几何体交错渲染时，可以稍微提高66属性的渲染性能。
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时，渲染器FRUSUM根据图元的边界体积剔除和地平线选择图元的命令。如果您手动剔除原语，请将此设置为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
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:

Members

readonly allowPicking : Boolean
Scene/Primitive.js 425

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

appearance : Appearance
Scene/Primitive.js 182

Appearance是用来给这个原始人着色的。每个几何体 实例以相同的外观着色。一些表象，比如 PerInstanceColorAppearance允许给每个实例唯一 属性。
Default Value: undefined

readonly asynchronous : Boolean
Scene/Primitive.js 441

确定几何体实例是否将在web工作器上创建和批处理。
Default Value: true

readonly compressVertices : Boolean
Scene/Primitive.js 457

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

cull : Boolean
Scene/Primitive.js 261

当true时，渲染器截锥和水平面剔除基本体的命令 基于它们的边界体积。将此值设置为false可获得较小的性能增益 如果手动剔除基本体。
Default Value: true

debugShowBoundingVolume : Boolean
Scene/Primitive.js 273

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

Draws the bounding sphere for each draw command in the primitive.

Default Value: false

depthFailAppearance : Appearance
Scene/Primitive.js 205

Appearance曾在深度测试失败时给这个原始体着色。每个几何体 实例以相同的外观着色。一些表象，比如 PerInstanceColorAppearance允许给每个实例唯一 属性。

When using an appearance that requires a color attribute, like PerInstanceColorAppearance, add a depthFailColor per-instance attribute instead.

Requires the EXT_frag_depth WebGL extension to render properly. If the extension is not supported, there may be artifacts.

Default Value: undefined

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

使用此基本体渲染的几何体实例。今年五月 如果是options.releaseGeometryInstances，则为undefined 构造原语时为true。

Changing this property after the primitive is rendered has no effect.

Default Value: undefined

readonly interleave : Boolean
Scene/Primitive.js 393

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

modelMatrix : Matrix4
Scene/Primitive.js 227

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

This property is only supported in 3D mode.

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 473

确定基本体是否已完成并准备好渲染。如果这个属性是 真的，下一次Primitive#update 被称为。

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

获取在原语准备呈现时解析的承诺。

readonly releaseGeometryInstances : Boolean
Scene/Primitive.js 409

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

shadows : ShadowMode
Scene/Primitive.js 303

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

show : Boolean
Scene/Primitive.js 240

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

readonly vertexCacheOptimize : Boolean
Scene/Primitive.js 377

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

Methods

destroy()
Scene/Primitive.js 2524

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

Once an object is destroyed, it should not be used; calling any function other than isDestroyed will result in a DeveloperError exception. Therefore, assign the return value (undefined) to the object as done in the example.

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

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

返回GeometryInstance的每个实例的可修改属性。
Name Type Description
id * GeometryInstance的id。
Returns:
属性格式的类型化数组，如果不是id为的实例，则为未定义数组。
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 2503

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

If this object was destroyed, it should not be used; calling any function other than isDestroyed will result in a DeveloperError exception.

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

update()
Scene/Primitive.js 2136

当Viewer或CesiumWidget将场景渲染到 获取渲染此基本体所需的draw命令。

Do not call this function directly. This is documented just to list the exceptions that may be propagated when the scene is rendered:

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