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:
|
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
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
Gets the number of primitives in the collection.
Determines if primitives in this collection will be shown.
-
Default Value:
true
Methods
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());
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.
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
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:
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:
Returns true if this object was destroyed; otherwise, false.
If this object was destroyed, it should not be used; calling any function other than
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.
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.
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.
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.
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.
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:
Removes all primitives in the collection.
Throws:
-
DeveloperError : This object was destroyed, i.e., destroy() was called.