BillboardCollection

new Cesium.BillboardCollection(options)

engine/Source/Scene/BillboardCollection.js 127

可渲染的广告牌集合。广告牌是定位在 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:

// 创建一个包含两个广告牌的集合
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) // 中心
});
billboards.add({
  image : 'url/to/image',
  position : new Cesium.Cartesian3(1000000.0, 0.0, 0.0) // 东
});
billboards.add({
  image : 'url/to/image',
  position : new Cesium.Cartesian3(0.0, 1000000.0, 0.0) // 北
});
billboards.add({
  image : 'url/to/image',
  position : new Cesium.Cartesian3(0.0, 0.0, 1000000.0) // 上
});

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:

// 示例 1：添加广告牌，指定所有默认值。
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
});

// 示例 2：仅指定广告牌的笛卡尔坐标位置。
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:

// 切换集合中每个广告牌的 show 属性
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);  // 返回 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 的图像必须在图集中。