BillboardCollection

new Cesium.BillboardCollection(options)

engine/Source/Scene/BillboardCollection.js 145

可渲染的广告牌集合。 公告板与视区对齐 位于 3D 场景中的图像。

广告牌示例

使用 BillboardCollection#add 在集合中添加和删除公告牌 和 BillboardCollection#remove。 集合中的公告板会自动共享纹理 表示具有相同标识符的图像。

Performance:

为了获得最佳性能，最好使用几个集合，每个集合都有许多广告牌，而不是 许多收藏，每个收藏只有几个广告牌。 组织集合，以便 billboards 具有相同更新频率的 billboard 位于同一集合中，即 更改应在一个集合中;更改每个帧的广告牌应该在另一个 收集;等等。

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 之前添加尽可能多的 billboard。

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:

预期恒定时间。 如果从集合中删除了 billboard，并且 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。 如果您打算暂时隐藏公告牌，通常调用 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 : image with id must be in the atlas.