BillboardCollection

new Cesium.BillboardCollection(options)

engine/Source/Scene/BillboardCollection.js 130

可渲染的广告牌集合。广告牌是位于 3D 场景中的视口对齐图像。 A renderable collection of billboards. Billboards are viewport-aligned images positioned in the 3D scene.

广告牌示例 Example billboards

使用以下方法在集合中添加和删除广告牌 Billboards are added and removed from the collection using BillboardCollection#add and BillboardCollection#remove。集合中的广告牌会自动共享具有相同标识符的图像的纹理。 . Billboards in a collection automatically share textures for images with the same identifier.

性能： Performance:

为了获得最佳性能，最好选择几个集合，每个集合都有许多广告牌，而不是多个集合，每个集合只有几个广告牌。整理集合，使更新频率相同的广告牌在同一个集合中，即不发生变化的广告牌应在一个集合中；每帧都改变的广告牌应该在另一个集合中；等等。 For best performance, prefer a few collections, each with many billboards, to many collections with only a few billboards each. Organize collections so that billboards with the same update frequency are in the same collection, i.e., billboards that do not change should be in one collection; billboards that change every frame should be in another collection; and so on.

名称 Name	类型 Type	说明 Description
options	object	可选 optional 具有以下属性的对象： Object with the following properties: 名称 Name 类型 Type 默认值 Default 说明 Description modelMatrix Matrix4 Matrix4.IDENTITY 可选 optional 将每个广告牌从模型转换到世界坐标的 4x4 转换矩阵。 The 4x4 transformation matrix that transforms each billboard from model to world coordinates. debugShowBoundingVolume boolean false 可选 optional 仅用于调试。确定是否显示该图元的命令的边界球体。 For debugging only. Determines if this primitive's commands' bounding spheres are shown. scene Scene 可选 optional 必须传入使用高度参考属性的广告牌或将针对地球进行深度测试。 Must be passed in for billboards that use the height reference property or will be depth tested against the globe. blendOption BlendOption BlendOption.OPAQUE_AND_TRANSLUCENT 可选 optional 广告牌混合选项。默认值用于渲染不透明和半透明的广告牌。但是，如果所有广告牌都完全不透明或完全半透明，则将技术设置为 BlendOption.OPAQUE 或 BlendOption.TRANSLUCENT 可以将性能提高多达 2 倍。 The billboard blending option. The default is used for rendering both opaque and translucent billboards. However, if either all of the billboards are completely opaque or all are completely translucent, setting the technique to BlendOption.OPAQUE or BlendOption.TRANSLUCENT can improve performance by up to 2x. show boolean true 可选 optional 确定是否显示集合中的广告牌。 Determines if the billboards in the collection will be shown. coarseDepthTestDistance number 可选 optional 距相机的距离，超过该距离，广告牌将根据地球椭球体的近似值而不是完整的地球深度缓冲区进行深度测试。如果未指定，则默认值是相对于以下值确定的 The distance from the camera, beyond which, billboards are depth-tested against an approximation of the globe ellipsoid rather than against the full globe depth buffer. If unspecified, the default value is determined relative to the value of Ellipsoid.default. threePointDepthTestDistance number 可选 optional 距摄像机的距离，在该距离内，广告牌上有 The distance from the camera, within which, billboards with a Billboard#heightReference 的价值 value of HeightReference.CLAMP_TO_GROUND or HeightReference.CLAMP_TO_TERRAIN 针对三个关键点进行深度测试。这确保了如果广告牌的任何关键点可见，则整个广告牌都将可见。如果未指定，则默认值是相对于以下值确定的 are depth tested against three key points. This ensures that if any key point of the billboard is visible, the whole billboard will be visible. If unspecified, the default value is determined relative to the value of Ellipsoid.default.

示例： Example:

// Create a billboard collection with two billboards
const billboards = scene.primitives.add(new Cesium.BillboardCollection());
billboards.add({
  position : new Cesium.Cartesian3(1.0, 2.0, 3.0),
  image : 'url/to/image'
});
billboards.add({
  position : new Cesium.Cartesian3(4.0, 5.0, 6.0),
  image : 'url/to/another/image'
});

演示： Demo:

• Cesium Sandcastle Billboard Demo

另见： See:

• BillboardCollection#add
• BillboardCollection#remove
• Billboard
• LabelCollection

成员 Members

默认值： Default Value: BlendOption.OPAQUE_AND_TRANSLUCENT

默认值： Default Value: false

默认值： Default Value: false

默认值： Default Value: Matrix4.IDENTITY

示例： Example:

const center = Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883);
billboards.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(center);
billboards.add({
  image : 'url/to/image',
  position : new Cesium.Cartesian3(0.0, 0.0, 0.0) // center
});
billboards.add({
  image : 'url/to/image',
  position : new Cesium.Cartesian3(1000000.0, 0.0, 0.0) // east
});
billboards.add({
  image : 'url/to/image',
  position : new Cesium.Cartesian3(0.0, 1000000.0, 0.0) // north
});
billboards.add({
  image : 'url/to/image',
  position : new Cesium.Cartesian3(0.0, 0.0, 1000000.0) // up
});

另见： See:

• Transforms.eastNorthUpToFixedFrame

默认值： Default Value: true

另见： See:

• Billboards and Labels on Terrain Improvements

方法 Methods

性能： Performance:

Calling add 是预期的常数时间。然而，集合的顶点缓冲区被重写 is expected constant time. However, the collection's vertex buffer is rewritten - an O(n) 操作也会产生 CPU 到 GPU 的开销。为了获得最佳性能，请在调用之前添加尽可能多的广告牌 operation that also incurs CPU to GPU overhead. For best performance, add as many billboards as possible before calling update.

返回： Returns:

抛出： Throws:

• DeveloperError : This object was destroyed, i.e., destroy() was called.

示例： Examples:

// Example 1:  Add a billboard, specifying all the default values.
const b = billboards.add({
  show : true,
  position : Cesium.Cartesian3.ZERO,
  pixelOffset : Cesium.Cartesian2.ZERO,
  eyeOffset : Cesium.Cartesian3.ZERO,
  heightReference : Cesium.HeightReference.NONE,
  horizontalOrigin : Cesium.HorizontalOrigin.CENTER,
  verticalOrigin : Cesium.VerticalOrigin.CENTER,
  scale : 1.0,
  image : 'url/to/image',
  imageSubRegion : undefined,
  color : Cesium.Color.WHITE,
  id : undefined,
  rotation : 0.0,
  alignedAxis : Cesium.Cartesian3.ZERO,
  width : undefined,
  height : undefined,
  scaleByDistance : undefined,
  translucencyByDistance : undefined,
  pixelOffsetScaleByDistance : undefined,
  sizeInMeters : false,
  distanceDisplayCondition : undefined
});

// Example 2:  Specify only the billboard's cartographic position.
const b = billboards.add({
  position : Cesium.Cartesian3.fromDegrees(longitude, latitude, height)
});

另见： See:

• BillboardCollection#remove
• BillboardCollection#removeAll

返回： Returns:

另见： See:

• BillboardCollection#get

抛出： Throws:

• DeveloperError : This object was destroyed, i.e., destroy() was called.

示例： Example:

billboards = billboards && billboards.destroy();

另见： See:

• BillboardCollection#isDestroyed

性能： Performance:

预期时间恒定。如果广告牌被从集合中移除并且 Expected constant time. If billboards were removed from the collection and BillboardCollection#update 没有被调用，隐式的 was not called, an implicit O(n) 执行操作。 operation is performed.

返回： Returns:

抛出： Throws:

• DeveloperError : This object was destroyed, i.e., destroy() was called.

示例： Example:

// Toggle the show property of every billboard in the collection
const len = billboards.length;
for (let i = 0; i < len; ++i) {
  const b = billboards.get(i);
  b.show = !b.show;
}

另见： See:

• BillboardCollection#length

返回： Returns:

另见： See:

• BillboardCollection#destroy

性能： Performance:

Calling remove 是预期的常数时间。然而，集合的顶点缓冲区被重写 is expected constant time. However, the collection's vertex buffer is rewritten - an O(n) 操作也会产生 CPU 到 GPU 的开销。为了获得最佳性能，请在调用之前删除尽可能多的广告牌 operation that also incurs CPU to GPU overhead. For best performance, remove as many billboards as possible before calling update。如果您打算暂时隐藏广告牌，通常拨打电话会更有效 . If you intend to temporarily hide a billboard, it is usually more efficient to call Billboard#show 而不是删除并重新添加广告牌。 instead of removing and re-adding the billboard.

返回： Returns:

抛出： Throws:

• DeveloperError : This object was destroyed, i.e., destroy() was called.

示例： Example:

const b = billboards.add(...);
billboards.remove(b);  // Returns true

另见： See:

• BillboardCollection#add
• BillboardCollection#removeAll
• Billboard#show

性能： Performance:

O(n)。从集合中删除所有广告牌然后添加新广告牌比完全创建新集合更有效。 . It is more efficient to remove all the billboards from a collection and then add new ones than to create a new collection entirely.

抛出： Throws:

• DeveloperError : This object was destroyed, i.e., destroy() was called.

示例： Example:

billboards.add(...);
billboards.add(...);
billboards.removeAll();

另见： See:

• BillboardCollection#add
• BillboardCollection#remove

抛出： Throws:

• RuntimeError : 带有id的图片必须在图集中。 : image with id must be in the atlas.