PrimitiveCollection — Cesium API reference

new Cesium.PrimitiveCollection(options)

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.

Name Type Description

options

object

optional Object with the following properties:

Name	Type	Default	Description
`show`	boolean	`true`	optional Determines if the primitives in the collection will be shown.
`destroyPrimitives`	boolean	`true`	optional Determines if primitives in the collection are destroyed when they are removed.

Example:

const billboards = new Cesium.BillboardCollection();
const labels = new Cesium.LabelCollection();

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

Default Value: true

Examples:

// Example 1. Primitives are destroyed by default.
const primitives = new Cesium.PrimitiveCollection();
const labels = primitives.add(new Cesium.LabelCollection());
primitives = primitives.destroy();
const b = labels.isDestroyed(); // true

// Example 2. Do not destroy primitives in a collection.
const primitives = new Cesium.PrimitiveCollection();
primitives.destroyPrimitives = false;
const labels = primitives.add(new Cesium.LabelCollection());
primitives = primitives.destroy();
const b = labels.isDestroyed(); // false
labels = labels.destroy();    // explicitly destroy

readonly length : number

Gets the number of primitives in the collection.

readonly primitiveAdded : Event

An event that is raised when a primitive is added to the collection. Event handlers are passed the primitive that was added.

readonly primitiveRemoved : Event

An event that is raised when a primitive is removed from the collection. Event handlers are passed the primitive that was removed.

Note: Depending on the destroyPrimitives constructor option, the primitive may already be destroyed.

show : boolean

Determines if primitives in this collection will be shown.

Default Value: true

Methods

add(primitive, index) → T

Adds a primitive to the collection.

Name	Type	Description
`primitive`	T	The primitive to add.
`index`	number	optional The index to add the layer at. If omitted, the primitive will be added at the bottom of all existing primitives.

Returns:

The primitive added to the collection.

Throws:

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

Example:

const billboards = scene.primitives.add(new Cesium.BillboardCollection());

contains(primitive) → boolean

Determines if this collection contains a primitive.

Name	Type	Description
`primitive`	object	optional The primitive to check for.

Returns:

true if the primitive is in the collection; false if the primitive is undefined or was not found in the collection.

Throws:

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

See:

PrimitiveCollection#get

destroy()

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.

Throws:

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

Example:

primitives = primitives && primitives.destroy();

See:

PrimitiveCollection#isDestroyed

get(index) → object

Returns the primitive in the collection at the specified index.

Name	Type	Description
`index`	number	The zero-based index of the primitive to return.

Returns:

The primitive at the index.

Throws:

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

Example:

// Toggle the show property of every primitive in the collection.
const primitives = scene.primitives;
const length = primitives.length;
for (let i = 0; i < length; ++i) {
  const p = primitives.get(i);
  p.show = !p.show;
}

See:

PrimitiveCollection#length

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:

PrimitiveCollection#destroy

lower(primitive)

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.

Name	Type	Description
`primitive`	object	optional The primitive to lower.

Throws:

DeveloperError : primitive is not in this collection.
DeveloperError : This object was destroyed, i.e., destroy() was called.

See:

PrimitiveCollection#lowerToBottom
PrimitiveCollection#raise
PrimitiveCollection#raiseToTop

lowerToBottom(primitive)

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.

Name	Type	Description
`primitive`	object	optional The primitive to lower to the bottom.

Throws:

DeveloperError : primitive is not in this collection.
DeveloperError : This object was destroyed, i.e., destroy() was called.

See:

PrimitiveCollection#lower
PrimitiveCollection#raise
PrimitiveCollection#raiseToTop

raise(primitive)

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.

Name	Type	Description
`primitive`	object	optional The primitive to raise.

Throws:

DeveloperError : primitive is not in this collection.
DeveloperError : This object was destroyed, i.e., destroy() was called.

See:

PrimitiveCollection#raiseToTop
PrimitiveCollection#lower
PrimitiveCollection#lowerToBottom

raiseToTop(primitive)

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.

Name	Type	Description
`primitive`	object	optional The primitive to raise the top.

Throws:

DeveloperError : primitive is not in this collection.
DeveloperError : This object was destroyed, i.e., destroy() was called.

See:

PrimitiveCollection#raise
PrimitiveCollection#lower
PrimitiveCollection#lowerToBottom

remove(primitive) → boolean

Removes a primitive from the collection.

Name	Type	Description
`primitive`	object	optional The primitive to remove.

Returns:

true if the primitive was removed; false if the primitive is undefined or was not found in the collection.

Throws:

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

Example:

const billboards = scene.primitives.add(new Cesium.BillboardCollection());
scene.primitives.remove(billboards);  // Returns true

See:

PrimitiveCollection#destroyPrimitives

removeAll()

Removes all primitives in the collection.

Throws:

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

See:

PrimitiveCollection#destroyPrimitives