# PrimitiveCollection - Cesium Documentation

# PrimitiveCollection

#### new Cesium.PrimitiveCollection(options)
Scene/PrimitiveCollection.js 40

  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:

      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
Scene/PrimitiveCollection.js 78

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

#### readonlylength : Number
Scene/PrimitiveCollection.js 90

  Gets the number of primitives in the collection.

#### show : Boolean
Scene/PrimitiveCollection.js 52

  Determines if primitives in this collection will be shown.
  Default Value: `true`

### Methods

#### add(primitive) → Object
Scene/PrimitiveCollection.js 108

  Adds a primitive to the collection.

  Name | Type | Description
  --- | --- | ---
  `primitive` | Object | The primitive to add.

  ##### Returns:

  The primitive added to the collection.

  ##### Throws:

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

  ##### Example:

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

#### contains(primitive) → Boolean
Scene/PrimitiveCollection.js 202

  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() → undefined
Scene/PrimitiveCollection.js 406

  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.

  ##### Returns:

  ##### Throws:

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

  ##### Example:

      primitives = primitives && primitives.destroy();

  ##### See:

  - PrimitiveCollection#isDestroyed

#### get(index) → Object
Scene/PrimitiveCollection.js 343

  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.
      var primitives = scene.primitives;
      var length = primitives.length;
      for (var i = 0; i < length; ++i) {
        var p = primitives.get(i);
        p.show = !p.show;
      }

  ##### See:

  - PrimitiveCollection#length

#### isDestroyed() → Boolean
Scene/PrimitiveCollection.js 380

  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)
Scene/PrimitiveCollection.js 284

  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)
Scene/PrimitiveCollection.js 310

  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)
Scene/PrimitiveCollection.js 232

  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)
Scene/PrimitiveCollection.js 258

  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
Scene/PrimitiveCollection.js 141

  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:

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

  ##### See:

  - PrimitiveCollection#destroyPrimitives

#### removeAll()
Scene/PrimitiveCollection.js 181

  Removes all primitives in the collection.

  ##### Throws:

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

  ##### See:

  - PrimitiveCollection#destroyPrimitives