PrimitiveCollection - Cesium Documentation

# PrimitiveCollection

#### new 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:

      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

  Source: Scene/PrimitiveCollection.js, line 40

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

  Source: Scene/PrimitiveCollection.js, line 78

#### readonlylength :Number

  Gets the number of primitives in the collection.
  Source: Scene/PrimitiveCollection.js, line 90

#### show :Boolean

  Determines if primitives in this collection will be shown.
  Default Value: `true`
  Source: Scene/PrimitiveCollection.js, line 52

### Methods

#### add(primitive) → Object

  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());

  Source: Scene/PrimitiveCollection.js, line 108

#### 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
  Source: Scene/PrimitiveCollection.js, line 201

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

  ##### Returns:

  ##### Throws:

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

  ##### Example:

      primitives = primitives && primitives.destroy();

  ##### See:

  - PrimitiveCollection#isDestroyed
  Source: Scene/PrimitiveCollection.js, line 403

#### 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.
      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
  Source: Scene/PrimitiveCollection.js, line 341

#### 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
  Source: Scene/PrimitiveCollection.js, line 378

#### 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
  Source: Scene/PrimitiveCollection.js, line 283

#### 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
  Source: Scene/PrimitiveCollection.js, line 309

#### 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
  Source: Scene/PrimitiveCollection.js, line 231

#### 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
  Source: Scene/PrimitiveCollection.js, line 257

#### 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:

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

  ##### See:

  - PrimitiveCollection#destroyPrimitives
  Source: Scene/PrimitiveCollection.js, line 140

#### removeAll()

  Removes all primitives in the collection.

  ##### Throws:

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

  ##### See:

  - PrimitiveCollection#destroyPrimitives
  Source: Scene/PrimitiveCollection.js, line 180