Primitive

new Cesium.Primitive ( options )

图元表示 Scene 中的几何图形。几何图形可以来自单个 GeometryInstance ,如下面的示例 1 所示,或者来自一个实例数组,即使几何图形来自不同的几何类型,例如代码示例 2 中所示的 RectangleGeometry EllipsoidGeometry

图元将几何实例与描述完整着色的 Appearance 组合在一起,包括 Material RenderState 。粗略地说,几何实例定义了结构和位置,外观定义了视觉特征。解耦几何和外观允许我们混合和匹配它们中的大多数,并相互独立地添加新的几何或外观。

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

Geometry 可以在 web worker 或主线程上创建和批处理。前两个示例显示了将使用几何描述在 Web Worker 上创建的几何。第三个示例显示了如何通过显式调用 createGeometry 方法在主线程上创建几何图形。

Name Type Description
options Object 具有以下属性的 可选 对象:
姓名 类型 默认 描述
geometryInstances 数组。< 几何实例 > | 几何实例 可选 要渲染的几何实例 - 或单个几何实例。
appearance 外貌 可选 用于渲染图元的外观。
depthFailAppearance 外貌 可选 当该图元未能通过深度测试时用于着色的外观。
show 布尔值 true 可选 确定是否显示此原语。
modelMatrix 矩阵4 Matrix4.IDENTITY 可选 将图元(所有几何实例)从模型转换为世界坐标的 4x4 转换矩阵。
vertexCacheOptimize 布尔值 false 可选 true 时,几何顶点针对顶点着色器前后缓存进行优化。
interleave 布尔值 false 可选 true 时,几何顶点属性是交错的,这可以稍微提高渲染性能但增加加载时间。
compressVertices 布尔值 true 可选 true 时,几何顶点被压缩,这将节省内存。
releaseGeometryInstances 布尔值 true 可选 true 时,基元不保留对输入 geometryInstances 的引用以节省内存。
allowPicking 布尔值 true 可选 true 时,每个几何实例只能通过 Scene#pick 来选择。当为 false 时,GPU 内存被保存。
cull 布尔值 true 可选 true 时,渲染器视锥体剔除和水平剔除基元的命令基于它们的边界体积。如果您手动剔除原语,请将其设置为 false 以获得较小的性能增益。
asynchronous 布尔值 true 可选 确定原语是异步创建还是阻塞直到准备好。
debugShowBoundingVolume 布尔值 false 可选 仅用于调试。确定是否显示此原语的命令的边界球。
shadows 阴影模式 ShadowMode.DISABLED 可选 确定此图元是否投射或接收来自光源的阴影。
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

当为 true 时,每个几何实例只能通过 Scene#pick 进行拾取。当为 false 时,GPU 内存被保存。 *
Default Value: true
用于着色此图元的 Appearance 。每个几何实例都以相同的外观着色。某些外观,例如 PerInstanceColorAppearance 允许为每个实例赋予唯一的属性。
Default Value: undefined

readonly asynchronous : Boolean

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

readonly compressVertices : Boolean

true 时,几何顶点被压缩,这将节省内存。
Default Value: true
当为 true 时,渲染器视锥体剔除和地平线根据其边界体积剔除基元的命令。如果您手动剔除原语,请将其设置为 false 以获得较小的性能增益。
Default Value: true

debugShowBoundingVolume : Boolean

该属性仅用于调试;它不是用于生产用途,也不是优化的。

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

Default Value: false
未通过深度测试时用于着色此图元的 Appearance 。每个几何实例都以相同的外观着色。某些外观,例如 PerInstanceColorAppearance 允许为每个实例赋予唯一的属性。

当使用需要颜色属性的外观(如 PerInstanceColorAppearance)时,请改为添加每个实例的 depthFailColor 属性。

需要 EXT_frag_depth WebGL 扩展才能正确呈现。如果不支持扩展,则可能存在工件。

Default Value: undefined
使用此图元渲染的几何实例。如果在构造图元时 options.releaseGeometryInstances true ,则这可能是 undefined 的。

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

Default Value: undefined

readonly interleave : Boolean

确定几何顶点属性是否交错,这可以稍微提高渲染性能。
Default Value: false
将图元(所有几何实例)从模型转换为世界坐标的 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

确定图元是否完整并准备好渲染。如果此属性为真,则基元将在下次调用 Primitive#update 时呈现。

readonly readyPromise : Promise.< Primitive >

获取当原语准备好渲染时解决的承诺。

readonly releaseGeometryInstances : Boolean

当为 true 时,图元不会保留对输入 geometryInstances 的引用以节省内存。
Default Value: true
确定此图元是投射还是接收来自光源的阴影。
Default Value: ShadowMode.DISABLED
确定是否将显示图元。这会影响图元中的所有几何实例。
Default Value: true

readonly vertexCacheOptimize : Boolean

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

Methods

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

一旦一个对象被销毁,它就不应该被使用;调用 isDestroyed 以外的任何函数都将导致 DeveloperError 异常。因此,如示例中所做的那样,将返回值 ( undefined ) 分配给对象。

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

getGeometryInstanceAttributes (id) Object

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

如果此对象被销毁,则返回 true;否则为假。

如果这个对象被破坏了,它就不应该被使用;调用 isDestroyed 以外的任何函数都将导致 DeveloperError 异常。

Returns:
如果此对象被销毁,则为 true ;否则, false
See:
Viewer CesiumWidget 渲染场景以获取渲染此图元所需的绘制命令时调用。

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

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