Primitive

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

图元表示Scene中的几何体。几何体可以来自单个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 4x4变换矩阵，将图元（所有几何实例）从模型坐标变换到世界坐标。
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 确定图元是异步创建还是阻塞直到就绪。
debugShowBoundingVolume boolean false optional 仅用于调试。确定是否显示此图元命令的包围球。
shadows ShadowMode ShadowMode.DISABLED optional 确定此图元是投射还是接收来自光源的阴影。
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
engine/Source/Scene/Primitive.js 405

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

appearance : Appearance
engine/Source/Scene/Primitive.js 178

用于对此图元进行着色的Appearance。每个几何实例使用相同的外观进行着色。 某些外观（如PerInstanceColorAppearance）允许为每个实例提供唯一的属性。
Default Value: undefined

readonly asynchronous : boolean
engine/Source/Scene/Primitive.js 421

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

readonly compressVertices : boolean
engine/Source/Scene/Primitive.js 437

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

cull : boolean
engine/Source/Scene/Primitive.js 245

当为true时，渲染器根据其包围体积对图元的命令进行视锥裁剪和地平线裁剪。 如果手动裁剪图元，将此设置为false可获得少量性能提升。
Default Value: true

debugShowBoundingVolume : boolean
engine/Source/Scene/Primitive.js 257

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

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

Default Value: false

depthFailAppearance : Appearance
engine/Source/Scene/Primitive.js 197

当图元深度测试失败时，用于对此图元进行着色的Appearance。每个几何实例使用相同的外观进行着色。 某些外观（如PerInstanceColorAppearance）允许为每个实例提供唯一的属性。

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

需要EXT_frag_depth WebGL扩展才能正确渲染。如果不支持该扩展，可能会出现伪影。

Default Value: undefined

readonly geometryInstances : Array.<GeometryInstance>|GeometryInstance
engine/Source/Scene/Primitive.js 168

与此图元一起渲染的几何实例。 如果在构造图元时options.releaseGeometryInstances为true， 则此属性可能为undefined。

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

Default Value: undefined

readonly interleave : boolean
engine/Source/Scene/Primitive.js 373

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

modelMatrix : Matrix4
engine/Source/Scene/Primitive.js 218

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
engine/Source/Scene/Primitive.js 465

确定图元是否完成并准备渲染。如果此属性为true， 则下次调用Primitive#update时将渲染该图元。
Example:
// 等待图元准备就绪后再访问属性
const removeListener = scene.postRender.addEventListener(() => {
  if (!frustumPrimitive.ready) {
    return;
  }

  const attributes = primitive.getGeometryInstanceAttributes('an id');
  attributes.color = Cesium.ColorGeometryInstanceAttribute.toValue(Cesium.Color.AQUA);

  removeListener();
});

readonly releaseGeometryInstances : boolean
engine/Source/Scene/Primitive.js 389

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

shadows : ShadowMode
engine/Source/Scene/Primitive.js 284

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

show : boolean
engine/Source/Scene/Primitive.js 228

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

readonly vertexCacheOptimize : boolean
engine/Source/Scene/Primitive.js 357

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

Methods

destroy()
engine/Source/Scene/Primitive.js 2440

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

对象销毁后，不应再使用它；调用除isDestroyed之外的任何函数都将导致DeveloperError异常。 因此，将返回值（undefined）赋给对象，如示例所示。

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

getGeometryInstanceAttributes(id) → object
engine/Source/Scene/Primitive.js 2353

返回GeometryInstance的可修改每实例属性。
Name Type Description
id * GeometryInstance的id。
Returns:
属性格式的类型的数组，如果不存在具有该id的实例则返回undefined。
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
engine/Source/Scene/Primitive.js 2420

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

如果此对象已销毁，则不应使用它；调用除isDestroyed之外的任何函数都将导致DeveloperError异常。

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

update()
engine/Source/Scene/Primitive.js 2065

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

不要直接调用此函数。此处仅用于文档说明，以列出渲染场景时可能传播的异常：

Throws:
  • DeveloperError : 所有实例几何体必须具有相同的primitiveType。
  • DeveloperError : 外观和材质具有同名的uniform。
  • DeveloperError : Primitive.modelMatrix仅在3D模式下支持。
  • RuntimeError : 渲染具有每实例属性的图元需要顶点纹理获取支持。顶点纹理图像单元的最大数量必须大于零。
Need help? The fastest way to get answers is from the community and team on the Cesium Forum.
CtrlK
packages/engine
packages/widgets