Class: PrimitiveCollection

PrimitiveCollection

new PrimitiveCollection(optionsopt)

A collection of primitives. This is most often used with Scene#primitives, but PrimitiveCollection is also a primitive itself so collections can be added to collections forming a hierarchy.
Parameters:
Name Type Attributes Description
options Object <optional>
 Object with the following properties:
Properties
Name Type Attributes Default Description
show Boolean <optional>
 true Determines if the primitives in the collection will be shown.
destroyPrimitives Boolean <optional>
 true Determines if primitives in the collection are destroyed when they are removed.
Source:
Example
var billboards = new Cesium.BillboardCollection();
var labels = new Cesium.LabelCollection();

var collection = new Cesium.PrimitiveCollection();
collection.add(billboards);

scene.primitives.add(collection);  // Add collection
scene.primitives.add(labels);      // Add regular primitive

Members

destroyPrimitives :Boolean

Determines if primitives in the collection are destroyed when they are removed by PrimitiveCollection#destroy or PrimitiveCollection#remove or implicitly by PrimitiveCollection#removeAll.
Type:
  • Boolean
Default Value:
  • true
Source:
Examples
// Example 1. Primitives are destroyed by default.
var primitives = new Cesium.PrimitiveCollection();
var labels = primitives.add(new Cesium.LabelCollection());
primitives = primitives.destroy();
var b = labels.isDestroyed(); // true
// Example 2. Do not destroy primitives in a collection.
var primitives = new Cesium.PrimitiveCollection();
primitives.destroyPrimitives = false;
var labels = primitives.add(new Cesium.LabelCollection());
primitives = primitives.destroy();
var b = labels.isDestroyed(); // false
labels = labels.destroy();    // explicitly destroy

(readonly) length :Number

Gets the number of primitives in the collection.
Type:
  • Number
Source:

show :Boolean

Determines if primitives in this collection will be shown.
Type:
  • Boolean
Default Value:
  • true
Source:

Methods

add(primitive) → {Object}

Adds a primitive to the collection.
Parameters:
Name Type Description
primitive Object The primitive to add.
Source:
Throws:
This object was destroyed, i.e., destroy() was called.
Type
DeveloperError
Returns:
The primitive added to the collection.
Type
Object
Example
var billboards = scene.primitives.add(new Cesium.BillboardCollection());

contains(primitiveopt) → {Boolean}

Determines if this collection contains a primitive.
Parameters:
Name Type Attributes Description
primitive Object <optional>
 The primitive to check for.
Source:
See:
Throws:
This object was destroyed, i.e., destroy() was called.
Type
DeveloperError
Returns:
true if the primitive is in the collection; false if the primitive is undefined or was not found in the collection.
Type
Boolean

destroy() → {undefined}

Destroys the WebGL resources held by each primitive in this collection. Explicitly destroying this collection allows for deterministic release of WebGL resources, instead of relying on the garbage collector to destroy this collection.

Since destroying a collection destroys all the contained primitives, only destroy a collection when you are sure no other code is still using any of the contained primitives.

Once this collection 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.
Source:
See:
Throws:
This object was destroyed, i.e., destroy() was called.
Type
DeveloperError
Returns:
Type
undefined
Example
primitives = primitives && primitives.destroy();

get(index) → {Object}

Returns the primitive in the collection at the specified index.
Parameters:
Name Type Description
index Number The zero-based index of the primitive to return.
Source:
See:
Throws:
This object was destroyed, i.e., destroy() was called.
Type
DeveloperError
Returns:
The primitive at the index.
Type
Object
Example
// Toggle the show property of every primitive in the collection.
var primitives = scene.primitives;
var length = primitives.length;
for (var i = 0; i < length; ++i) {
  var p = primitives.get(i);
  p.show = !p.show;
}

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.
Source:
See:
Returns:
True if this object was destroyed; otherwise, false.
Type
Boolean

lower(primitiveopt)

Lowers a primitive "down one" in the collection. If all primitives in the collection are drawn on the globe surface, this visually moves the primitive down one.
Parameters:
Name Type Attributes Description
primitive Object <optional>
 The primitive to lower.
Source:
See:
Throws:

lowerToBottom(primitiveopt)

Lowers a primitive to the "bottom" of the collection. If all primitives in the collection are drawn on the globe surface, this visually moves the primitive to the bottom.
Parameters:
Name Type Attributes Description
primitive Object <optional>
 The primitive to lower to the bottom.
Source:
See:
Throws:

raise(primitiveopt)

Raises a primitive "up one" in the collection. If all primitives in the collection are drawn on the globe surface, this visually moves the primitive up one.
Parameters:
Name Type Attributes Description
primitive Object <optional>
 The primitive to raise.
Source:
See:
Throws:

raiseToTop(primitiveopt)

Raises a primitive to the "top" of the collection. If all primitives in the collection are drawn on the globe surface, this visually moves the primitive to the top.
Parameters:
Name Type Attributes Description
primitive Object <optional>
 The primitive to raise the top.
Source:
See:
Throws:

remove(primitiveopt) → {Boolean}

Removes a primitive from the collection.
Parameters:
Name Type Attributes Description
primitive Object <optional>
 The primitive to remove.
Source:
See:
Throws:
This object was destroyed, i.e., destroy() was called.
Type
DeveloperError
Returns:
true if the primitive was removed; false if the primitive is undefined or was not found in the collection.
Type
Boolean
Example
var billboards = scene.primitives.add(new Cesium.BillboardCollection());
scene.primitives.remove(p);  // Returns true

removeAll()

Removes all primitives in the collection.
Source:
See:
Throws:
This object was destroyed, i.e., destroy() was called.
Type
DeveloperError