# PrimitiveCollection

#### new Cesium.PrimitiveCollection(options)
engine/Source/Scene/PrimitiveCollection.js 33

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
engine/Source/Scene/PrimitiveCollection.js 76

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
engine/Source/Scene/PrimitiveCollection.js 90

Gets the number of primitives in the collection.

#### readonly primitiveAdded : Event
engine/Source/Scene/PrimitiveCollection.js 103

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
engine/Source/Scene/PrimitiveCollection.js 119

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
engine/Source/Scene/PrimitiveCollection.js 50

Determines if primitives in this collection will be shown.

Default Value: `true`

### Methods

#### add(primitive, index) → object
engine/Source/Scene/PrimitiveCollection.js 138

Adds a primitive to the collection.

Name | Type | Description
--- | --- | ---
`primitive` | object | 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
engine/Source/Scene/PrimitiveCollection.js 276

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()
engine/Source/Scene/PrimitiveCollection.js 528

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
engine/Source/Scene/PrimitiveCollection.js 419

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
engine/Source/Scene/PrimitiveCollection.js 504

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)
engine/Source/Scene/PrimitiveCollection.js 360

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)
engine/Source/Scene/PrimitiveCollection.js 386

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)
engine/Source/Scene/PrimitiveCollection.js 308

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)
engine/Source/Scene/PrimitiveCollection.js 334

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
engine/Source/Scene/PrimitiveCollection.js 196

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()
engine/Source/Scene/PrimitiveCollection.js 244

Removes all primitives in the collection.

##### Throws:

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

##### See:

- PrimitiveCollection#destroyPrimitives

Need help? The fastest way to get answers is from the community and team on the Cesium Forum.