BillboardCollection

new Cesium.BillboardCollection(options)

engine/Source/Scene/BillboardCollection.js 139

可渲染的广告牌集合。广告牌是视口对齐的 图像，定位于 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 确定集合中的广告牌是否可见。

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

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 的图像必须在图集中。