BillboardCollection

new BillboardCollection()

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. All billboards in a collection reference images from the same texture atlas, which is assigned using BillboardCollection#textureAtlas.

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.

Name	Type	Default	Description
options.modelMatrix	Matrix4	Matrix4.IDENTITY	optional The 4x4 transformation matrix that transforms each billboard from model to world coordinates.
options.debugShowBoundingVolume	Boolean	false	optional For debugging only. Determines if this primitive's commands' bounding spheres are shown.

Example:

// Create a billboard collection with two billboards
var billboards = new Cesium.BillboardCollection();
var atlas = new TextureAtlas({
  scene : scene,
  images : images
});
billboards.textureAtlas = atlas;
billboards.add({
  position : { x : 1.0, y : 2.0, z : 3.0 },
  imageIndex : 0
});
billboards.add({
  position : { x : 4.0, y : 5.0, z : 6.0 },
  imageIndex : 1
});

Demo:

• Cesium Sandcastle Billboard Demo

See:

• BillboardCollection#add
• BillboardCollection#remove
• BillboardCollection#textureAtlas
• Billboard
• TextureAtlas
• LabelCollection

Source: Scene/BillboardCollection.js, line 145

Members

debugShowBoundingVolume :Boolean

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

Draws the bounding sphere for each DrawCommand in the primitive.

Default Value: false

Source: Scene/BillboardCollection.js, line 230

destroyTextureAtlas :Boolean

Gets and sets the destroyTextureAtlas, which determines if the texture atlas is destroyed when the collection is destroyed. If the texture atlas is used by more than one collection, set this to false, and explicitly destroy the atlas to avoid attempting to destroy it multiple times.

Example:

// Set destroyTextureAtlas
// Destroy a billboard collection but not its texture atlas.

var atlas = new TextureAtlas({
  scene : scene,
  images : images
});
billboards.textureAtlas = atlas;
billboards.destroyTextureAtlas = false;
billboards = billboards.destroy();
console.log(atlas.isDestroyed()); // False

Source: Scene/BillboardCollection.js, line 338

length :Number

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

Source: Scene/BillboardCollection.js, line 269

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 returned by Transforms.eastNorthUpToFixedFrame. This matrix is available to GLSL vertex and fragment shaders via czm_model and derived uniforms.

Default Value: Matrix4.IDENTITY

Example:

var center = Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883);
billboards.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(center);
billboards.add({ imageIndex: 0, position : new Cesium.Cartesian3(0.0, 0.0, 0.0) }); // center
billboards.add({ imageIndex: 0, position : new Cesium.Cartesian3(1000000.0, 0.0, 0.0) }); // east
billboards.add({ imageIndex: 0, position : new Cesium.Cartesian3(0.0, 1000000.0, 0.0) }); // north
billboards.add({ imageIndex: 0, position : new Cesium.Cartesian3(0.0, 0.0, 1000000.0) }); // up
]);

See:

• Transforms.eastNorthUpToFixedFrame
• czm_model

Source: Scene/BillboardCollection.js, line 217

textureAtlas :TextureAtlas

Gets and sets the textureAtlas.

Example:

// Set the texture atlas
// Assigns a texture atlas with two images to a billboard collection.
// Two billboards, each referring to one of the images, are then
// added to the collection.
var billboards = new Cesium.BillboardCollection();
var images = [image0, image1];
var atlas = new TextureAtlas({
  scene : scene,
  images : images
});
billboards.textureAtlas = atlas;
billboards.add({
  // ...
  imageIndex : 0
});
billboards.add({
  // ...
  imageIndex : 1
});

Source: Scene/BillboardCollection.js, line 302

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

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.

Example:

// 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,
  horizontalOrigin : Cesium.HorizontalOrigin.CENTER,
  verticalOrigin : Cesium.VerticalOrigin.CENTER,
  scale : 1.0,
  imageIndex : 0,
  color : Cesium.Color.WHITE,
  id : undefined
});

// Example 2:  Specify only the billboard's cartographic position.
var b = billboards.add({
  position : ellipsoid.cartographicToCartesian(new Cesium.Cartographic(longitude, latitude, height))
});

See:

• BillboardCollection#remove
• BillboardCollection#removeAll

Source: Scene/BillboardCollection.js, line 387

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:

• BillboardCollection#get

Source: Scene/BillboardCollection.js, line 500

destroy() → undefined

Destroys the WebGL resources held by this object. Destroying an object allows for deterministic release 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 than isDestroyed 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:

• BillboardCollection#isDestroyed

Source: Scene/BillboardCollection.js, line 1385

get(index) → Billboard

Returns the billboard in the collection at the specified index. Indices are zero-based and increase as billboards are added. Removing a billboard shifts all billboards after it to the left, changing their indices. This function is commonly used with BillboardCollection#length to iterate over all the billboards in the collection.

Performance:

Expected constant time. If billboards were removed from the collection and BillboardCollection#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:

• BillboardCollection#length

Source: Scene/BillboardCollection.js, line 533

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 than isDestroyed will result in a DeveloperError exception.

Returns:

true if this object was destroyed; otherwise, false.

See:

• BillboardCollection#destroy

Source: Scene/BillboardCollection.js, line 1362

remove(billboard) → Boolean

Removes a billboard from the collection.

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.

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:

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

Source: Scene/BillboardCollection.js, line 422

removeAll()

Removes all billboards from the collection.

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.

Example:

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

See:

• BillboardCollection#add
• BillboardCollection#remove

Source: Scene/BillboardCollection.js, line 452