BillboardCollection

查阅Mars3D API

new Cesium.BillboardCollection(options)

engine/Source/Scene/BillboardCollection.js 145

A renderable collection of billboards. Billboards are viewport-aligned images positioned in the 3D scene.

Example billboards

Billboards are added and removed from the collection using BillboardCollection#add and BillboardCollection#remove. Billboards in a collection automatically share textures for images with the same identifier.

Performance:

For best performance, prefer a few collections, each with many billboards, to many collections with only a few billboards each. Organize collections so that billboards with the same update frequency are in the same collection, i.e., billboards that do not change should be in one collection; billboards that change every frame should be in another collection; and so on.

参数名称	类型	描述信息
options	object	可选 Object with the following properties: 参数名称 类型 默认值 描述信息 modelMatrix Matrix4 Matrix4.IDENTITY 可选 The 4x4 transformation matrix that transforms each billboard from model to world coordinates. debugShowBoundingVolume boolean false 可选 For debugging only. Determines if this primitive's commands' bounding spheres are shown. scene Scene 可选 Must be passed in for billboards that use the height reference property or will be depth tested against the globe. blendOption BlendOption BlendOption.OPAQUE_AND_TRANSLUCENT 可选 The billboard blending option. The default is used for rendering both opaque and translucent billboards. However, if either all of the billboards are completely opaque or all are completely translucent, setting the technique to BlendOption.OPAQUE or BlendOption.TRANSLUCENT can improve performance by up to 2x. show boolean true 可选 Determines if the billboards in the collection will be shown.

使用示例:

// 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

参考:

• BillboardCollection#add
• BillboardCollection#remove
• Billboard
• LabelCollection

成员(属性)

默认值: BlendOption.OPAQUE_AND_TRANSLUCENT

默认值: false

默认值: false

默认值: Matrix4.IDENTITY

使用示例:

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
});

参考:

• Transforms.eastNorthUpToFixedFrame

默认值: true

方法

Performance:

Calling add is expected constant time. However, the collection's vertex buffer is rewritten - an O(n) operation that also incurs CPU to GPU overhead. For best performance, add as many billboards as possible before calling update.

返回值:

Throws:

• DeveloperError : This object was destroyed, i.e., destroy() was called.

使用示例s:

// 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)
});

参考:

• BillboardCollection#remove
• BillboardCollection#removeAll

返回值:

参考:

• BillboardCollection#get

Throws:

• DeveloperError : This object was destroyed, i.e., destroy() was called.

使用示例:

billboards = billboards && billboards.destroy();

参考:

• BillboardCollection#isDestroyed

Performance:

Expected constant time. If billboards were removed from the collection and BillboardCollection#update was not called, an implicit O(n) operation is performed.

返回值:

Throws:

• DeveloperError : This object was destroyed, i.e., destroy() was called.

使用示例:

// 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;
}

参考:

• BillboardCollection#length

返回值:

参考:

• BillboardCollection#destroy

Performance:

Calling remove is expected constant time. However, the collection's vertex buffer is rewritten - an O(n) operation that also incurs CPU to GPU overhead. For best performance, remove as many billboards as possible before calling update. If you intend to temporarily hide a billboard, it is usually more efficient to call Billboard#show instead of removing and re-adding the billboard.

返回值:

Throws:

• DeveloperError : This object was destroyed, i.e., destroy() was called.

使用示例:

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

参考:

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

Performance:

O(n). It is more efficient to remove all the billboards from a collection and then add new ones than to create a new collection entirely.

Throws:

• DeveloperError : This object was destroyed, i.e., destroy() was called.

使用示例:

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

参考:

• BillboardCollection#add
• BillboardCollection#remove

Throws:

• RuntimeError : image with id must be in the atlas.