BillboardCollection

new Cesium.BillboardCollection(options)

engine/Source/Scene/BillboardCollection.js 130

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

广告牌示例

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

Performance:

为获得最佳性能，建议使用少量集合，每个集合包含大量广告牌，而不是使用大量集合，每个集合只包含少量广告牌。组织集合时，应将具有相同更新频率的广告牌放在同一集合中，即，不变化的广告牌放在一个集合中；每帧都变化的广告牌放在另一个集合中；以此类推。

Name	Type	Description
options	object	optional 具有以下属性的对象： Name Type Default Description modelMatrix Matrix4 Matrix4.IDENTITY optional 将每个广告牌从模型坐标变换到世界坐标的 4x4 变换矩阵。 debugShowBoundingVolume boolean false optional 仅用于调试。确定是否显示此图元的命令的包围球。 scene Scene optional 对于使用高度参考属性或将对地球进行深度测试的广告牌，必须传入此参数。 blendOption BlendOption BlendOption.OPAQUE_AND_TRANSLUCENT optional 广告牌混合选项。默认值用于渲染不透明和半透明的广告牌。但是，如果所有广告牌都是完全不透明的或全部都是完全半透明的，将技术设置为 BlendOption.OPAQUE 或 BlendOption.TRANSLUCENT 可以将性能提升最多 2 倍。 show boolean true optional 确定集合中的广告牌是否显示。 coarseDepthTestDistance number optional 与相机的距离，超过此距离后，广告牌将针对地球椭球体的近似值进行深度测试，而不是针对完整的地球深度缓冲区。如果未指定，默认值将根据 Ellipsoid.default 的值确定。 threePointDepthTestDistance number optional 与相机的距离，在此距离内，Billboard#heightReference 值为 HeightReference.CLAMP_TO_GROUND 或 HeightReference.CLAMP_TO_TERRAIN 的广告牌将针对三个关键点进行深度测试。这确保如果广告牌的任何关键点可见，整个广告牌都将可见。如果未指定，默认值将根据 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:

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

Returns:

Throws:

• DeveloperError : 此对象已被销毁，即 destroy() 已被调用。

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 : 此对象已被销毁，即 destroy() 已被调用。

Example:

billboards = billboards && billboards.destroy();

See:

• BillboardCollection#isDestroyed

Performance:

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

Returns:

Throws:

• DeveloperError : 此对象已被销毁，即 destroy() 已被调用。

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:

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

Returns:

Throws:

• DeveloperError : 此对象已被销毁，即 destroy() 已被调用。

Example:

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

See:

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

Performance:

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

Throws:

• DeveloperError : 此对象已被销毁，即 destroy() 已被调用。

Example:

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

See:

• BillboardCollection#add
• BillboardCollection#remove

Throws:

• RuntimeError : 带有 id 的图像必须在图集中。