BillboardCollection

new Cesium.BillboardCollection ( options )
Scene/BillboardCollection.js 142

可渲染的广告牌集合。广告牌是位于 3D 场景中的视口对齐图像。


示例广告牌


使用 BillboardCollection#add 和 BillboardCollection#remove 从集合中添加和删除广告牌。集合中的广告牌会自动共享具有相同标识符的图像的纹理。
Performance:

为了获得最佳性能，最好选择几个集合，每个集合都有很多广告牌，而不是多个集合，每个集合只有几个广告牌。整理收藏，使更新频率相同的广告牌在同一个收藏中，即不发生变化的广告牌在一个收藏中；改变每一帧的广告牌应该在另一个集合中；等等。

Name Type Description
options Object 具有以下属性的 可选 对象:
姓名 类型 默认 描述
modelMatrix 矩阵4 Matrix4.IDENTITY 可选 将每个广告牌从模型转换为世界坐标的 4x4 转换矩阵。
debugShowBoundingVolume 布尔值 false 可选 仅用于调试。确定是否显示此原语的命令的边界球。
scene 场景 可选 对于使用高度参考属性或将针对地球进行深度测试的广告牌，必须传入。
blendOption 混合选项 BlendOption.OPAQUE_AND_TRANSLUCENT 可选 广告牌混合选项。默认值用于渲染不透明和半透明的广告牌。但是，如果所有广告牌都完全不透明或完全半透明，则将技术设置为 BlendOption.OPAQUE 或 BlendOption.TRANSLUCENT 可以将性能提高多达 2 倍。
show 布尔值 true 可选 确定是否显示集合中的广告牌。
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:
See:

Members

blendOption : BlendOption
Scene/BillboardCollection.js 288

广告牌混合选项。默认值用于渲染不透明和半透明的广告牌。但是，如果所有广告牌都完全不透明或完全半透明，则将技术设置为 BlendOption.OPAQUE 或 BlendOption.TRANSLUCENT 可以将性能提高多达 2 倍。
Default Value: BlendOption.OPAQUE_AND_TRANSLUCENT

debugShowBoundingVolume : Boolean
Scene/BillboardCollection.js 260

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

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

Default Value: false

debugShowTextureAtlas : Boolean
Scene/BillboardCollection.js 275

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

将此 BillboardCollection 的纹理图集绘制为全屏四边形。

Default Value: false

length : Number
Scene/BillboardCollection.js 353

返回此集合中的广告牌数量。这通常与 BillboardCollection#get 一起使用以遍历集合中的所有广告牌。

modelMatrix : Matrix4
Scene/BillboardCollection.js 245

将此集合中的每个广告牌从模型转换为世界坐标的 4x4 转换矩阵。当这是单位矩阵时，广告牌是在世界坐标中绘制的，即地球的 WGS84 坐标。可以通过提供不同的变换矩阵来使用本地参考帧，就像 Transforms.eastNorthUpToFixedFrame 返回的那样。
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:

show : Boolean
Scene/BillboardCollection.js 211

确定是否显示此集合中的广告牌。
Default Value: true

Methods

add ( options ) → Billboard
Scene/BillboardCollection.js 474

创建具有指定初始属性的广告牌并将其添加到集合中。添加的广告牌被返回，以便以后可以修改或从集合中删除。
Performance:

调用 add 是预期的恒定时间。但是，集合的顶点缓冲区被重写 - 一个 O(n) 操作，也会导致 CPU 到 GPU 开销。为了获得最佳性能，请在调用 update 之前添加尽可能多的广告牌。

Name Type Description
options Object 可选 描述广告牌属性的模板，如示例 1 所示。
Returns:
添加到集合中的广告牌。
Throws:
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:

contains ( billboard ) → Boolean
Scene/BillboardCollection.js 584

检查此集合是否包含给定的广告牌。
Name Type Description
billboard Billboard 可选 要检查的广告牌。
Returns:
如果此集合包含广告牌，则为 true，否则为 false。
See:

destroy ()
Scene/BillboardCollection.js 2400

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

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

get (index) → Billboard
Scene/BillboardCollection.js 615

返回集合中指定索引处的广告牌。指数从零开始，随着广告牌的添加而增加。移除广告牌会将其后的所有广告牌向左移动，从而更改它们的索引。此函数通常与 BillboardCollection#length 一起使用以遍历集合中的所有广告牌。
Performance:

预期的恒定时间。如果从集合中删除了广告牌并且未调用 BillboardCollection#update ，则执行隐式 O(n) 操作。

Name Type Description
index Number 广告牌的从零开始的索引。
Returns:
指定索引处的广告牌。
Throws:
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:

isDestroyed () → Boolean
Scene/BillboardCollection.js 2380

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

如果这个对象被破坏了，它就不应该被使用；调用 isDestroyed 以外的任何函数都将导致 DeveloperError 异常。
Returns:
如果此对象被销毁，则为 true ；否则， false 。
See:

remove (billboard) → Boolean
Scene/BillboardCollection.js 507

从集合中删除广告牌。
Performance:

调用 remove 是预期的恒定时间。但是，集合的顶点缓冲区被重写 - 一个 O(n) 操作，也会导致 CPU 到 GPU 开销。为了获得最佳性能，请在调用 update 之前删除尽可能多的广告牌。如果您打算暂时隐藏广告牌，调用 Billboard#show 通常比删除并重新添加广告牌更有效。

Name Type Description
billboard Billboard 要删除的广告牌。
Returns:
如果广告牌被移除，则为 true ；如果在集合中未找到广告牌，则返回 false 。
Throws:
Example: 
const b = billboards.add(...);
billboards.remove(b);  // Returns true
See:

removeAll ()
Scene/BillboardCollection.js 536

从集合中删除所有广告牌。
Performance:

O(n) 。从集合中删除所有广告牌然后添加新广告牌比完全创建新集合更有效。

Throws:
Example: 
billboards.add(...);
billboards.add(...);
billboards.removeAll();
See:

update ()
Scene/BillboardCollection.js 1821

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

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

Throws: