BillboardCollection

new Cesium.BillboardCollection(options)

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


Example billboards


Billboards are added and removed from the collection using BillboardCollection#addand BillboardCollection#remove. Billboards in a collection automatically share texturesfor images with the same identifier.
Performance:

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

Name Type Description
options Object optional Object with the following properties:
Name Type Default Description
modelMatrix Matrix4 Matrix4.IDENTITY optional The 4x4 transformation matrix that transforms each billboard from model to world coordinates.
debugShowBoundingVolume Boolean false optional For debugging only. Determines if this primitive's commands' bounding spheres are shown.
scene Scene optional 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 optional The billboard blending option. The defaultis 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 BillboardRenderTechnique.OPAQUE or BillboardRenderTechnique.TRANSLUCENT can improve performance by up to 2x.
Example:
// Create a billboard collection with two billboards
var 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:
See:

Members

blendOption : BlendOption

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 BillboardRenderTechnique.OPAQUE or BillboardRenderTechnique.TRANSLUCENT can improveperformance by up to 2x.
Default Value: BlendOption.OPAQUE_AND_TRANSLUCENT

debugShowBoundingVolume : Boolean

This property is for debugging only; it is not for production use nor is it optimized.

Draws the bounding sphere for each draw command in the primitive.

Default Value: false

length : Number

Returns the number of billboards in this collection. This is commonly used withBillboardCollection#get to iterate over all the billboardsin the collection.

modelMatrix : Matrix4

The 4x4 transformation matrix that transforms each billboard in this collection from model to world coordinates.When this is the identity matrix, the billboards are drawn in world coordinates, i.e., Earth's WGS84 coordinates.Local reference frames can be used by providing a different transformation matrix, like that returnedby Transforms.eastNorthUpToFixedFrame.
Default Value: Matrix4.IDENTITY
Example:
var 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:

Methods

add(billboard) → Billboard

Creates and adds a billboard with the specified initial properties to the collection.The added billboard is returned so it can be modified or removed from the collection later.
Performance:

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

Name Type Description
billboard Object optional A template describing the billboard's properties as shown in Example 1.
Returns:
The billboard that was added to the collection.
Throws:
  • DeveloperError : This object was destroyed, i.e., destroy() was called.
Examples:
// Example 1:  Add a billboard, specifying all the default values.
var 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.
var b = billboards.add({
  position : Cesium.Cartesian3.fromDegrees(longitude, latitude, height)
});
See:

contains(billboard) → Boolean

Check whether this collection contains a given billboard.
Name Type Description
billboard Billboard optional The billboard to check for.
Returns:
true if this collection contains the billboard, false otherwise.
See:

destroy() → undefined

Destroys the WebGL resources held by this object. Destroying an object allows for deterministicrelease of WebGL resources, instead of relying on the garbage collector to destroy this object.

Once an object is destroyed, it should not be used; calling any function other thanisDestroyed will result in a DeveloperError exception. Therefore,assign the return value (undefined) to the object as done in the example.
Returns:
Throws:
  • DeveloperError : This object was destroyed, i.e., destroy() was called.
Example:
billboards = billboards && billboards.destroy();
See:

get(index) → Billboard

Returns the billboard in the collection at the specified index. Indices are zero-basedand increase as billboards are added. Removing a billboard shifts all billboards afterit to the left, changing their indices. This function is commonly used withBillboardCollection#length to iterate over all the billboardsin the collection.
Performance:

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

Name Type Description
index Number The zero-based index of the billboard.
Returns:
The billboard at the specified index.
Throws:
  • DeveloperError : This object was destroyed, i.e., destroy() was called.
Example:
// Toggle the show property of every billboard in the collection
var len = billboards.length;
for (var i = 0; i < len; ++i) {
  var b = billboards.get(i);
  b.show = !b.show;
}
See:

isDestroyed() → Boolean

Returns true if this object was destroyed; otherwise, false.

If this object was destroyed, it should not be used; calling any function other thanisDestroyed will result in a DeveloperError exception.
Returns:
true if this object was destroyed; otherwise, false.
See:

remove(billboard) → Boolean

Removes a billboard from the collection.
Performance:

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

Name Type Description
billboard Billboard The billboard to remove.
Returns:
true if the billboard was removed; false if the billboard was not found in the collection.
Throws:
  • DeveloperError : This object was destroyed, i.e., destroy() was called.
Example:
var b = billboards.add(...);
billboards.remove(b);  // Returns true
See:

removeAll()

Removes all billboards from the collection.
Performance:

O(n). It is more efficient to remove all the billboardsfrom 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.
Example:
billboards.add(...);
billboards.add(...);
billboards.removeAll();
See:

update()

Called when Viewer or CesiumWidget render the scene toget the draw commands needed to render this primitive.

Do not call this function directly. This is documented just tolist the exceptions that may be propagated when the scene is rendered:

Throws: