Class: BillboardCollection

BillboardCollection

new BillboardCollection()

A collection of renderable bulletin boards.


Example billboards
Billboards can be BillboardCollection#add and BillboardCollection#remove added to and removed from the collection.Billboards in the collection automatically share image textures with the same identifier.
Name Type Default Description
options.modelMatrix Matrix4 Matrix4.IDENTITY optional

4x4 transformation matrix, used to transform each bulletin board from the model to geographic coordinates.
options.debugShowBoundingVolume Boolean false optional

Only for debugging purposes. Determine whether to display the command bounding ball for the primitive.
options.scene Scene optional

For bulletin boards that use the height reference attribute or will undergo depth testing based on the Earth, this parameter must be entered.
options.blendOption BlendOption BlendOption.OPAQUE_AND_TRANSLUCENT optional

Mixed options for bulletin boards. Default for rendering opaque and semi transparent bulletin boards. However, if all bulletin boards are completely opaque or semi transparent, set the technique to BillboardRender Technique. OPAQUE or BillboardRender Technique. Translucent can increase performance by 2 times.
See:
Example
// Create a billboard collection with two billboards
var billboards = scene.primitives.add(new SuperMap3D.BillboardCollection({scene:scene}));
billboards.add({
  position : new SuperMap3D.Cartesian3(1.0, 2.0, 3.0),
  image : 'url/to/image'
});
billboards.add({
  position : new SuperMap3D.Cartesian3(4.0, 5.0, 6.0),
  image : 'url/to/another/image'
});

Members

blendOptionBlendOption

Mixed options for bulletin boards. The default value is used to render opaque and semi transparent bulletin boards. However, if all bulletin boards are completely opaque or semi transparent, setting the technology to BillboardRenderTechnologe.OPAQUE or BillboardRenderTechnology.TRANSLUCENT can increase performance by up to 2 times.

Default Value:
BlendOption.OPAQUE_AND_TRANSLUCENT

debugShowBoundingVolumeBoolean

This property is only used for debugging to draw a bounding ball for each drawing command in the primitive.

Default Value:
false

debugShowTextureAtlasBoolean

This property is for debugging only; it is not for production use nor is it optimized.

Draws the texture atlas for this BillboardCollection as a fullscreen quad.

Default Value:
false

lengthNumber

Return the number of bulletin boards in this collection. Usually used in conjunction with BillboardCollection # get to traverse all bulletin boards in a collection.

modelMatrixMatrix4

Convert each bulletin board in this set from the model to geographic coordinates using a 4x4 transformation matrix. When this is an identity matrix, the bulletin board is drawn in geographic coordinates, i.e. WGS84 coordinates. Local reference frames can be used by providing different transformation matrices, just like what Transforms.eastNorthUpToFixedFrame returns.

Default Value:
Matrix4.IDENTITY
See:
Example
var center = SuperMap3D.Cartesian3.fromDegrees(-75.59777, 40.03883);
billboards.modelMatrix = SuperMap3D.Transforms.eastNorthUpToFixedFrame(center);
billboards.add({
  image : 'url/to/image',
  position : new SuperMap3D.Cartesian3(0.0, 0.0, 0.0) // center
});
billboards.add({
  image : 'url/to/image',
  position : new SuperMap3D.Cartesian3(1000000.0, 0.0, 0.0) // east
});
billboards.add({
  image : 'url/to/image',
  position : new SuperMap3D.Cartesian3(0.0, 1000000.0, 0.0) // north
});
billboards.add({
  image : 'url/to/image',
  position : new SuperMap3D.Cartesian3(0.0, 0.0, 1000000.0) // up
});

Methods

add(billboard){Billboard}

Create a bulletin board with specified initial properties and add it to the collection. The added bulletin board will be returned for future modification or removal from the collection.

Name Type Description
billboard Object optional

Template for describing bulletin board properties, as shown in Example 1.
See:
Throws:

The object is destroyed by calling destroy().

Type
DeveloperError
Returns:
Type Description
Billboard Join the bulletin board of this series. Calling add is the expected constant time. However, rewriting the vertex buffer of the set with a 0 (n) operation can also result in CPU to GPU overhead. To achieve optimal performance, add as many bulletin boards as possible before calling update.
Examples
// Example 1:  Add a billboard, specifying all the default values.
var b = billboards.add({
  show : true,
  position : SuperMap3D.Cartesian3.ZERO,
  pixelOffset : SuperMap3D.Cartesian2.ZERO,
  eyeOffset : SuperMap3D.Cartesian3.ZERO,
  heightReference : SuperMap3D.HeightReference.NONE,
  horizontalOrigin : SuperMap3D.HorizontalOrigin.CENTER,
  verticalOrigin : SuperMap3D.VerticalOrigin.CENTER,
  scale : 1.0,
  image : 'url/to/image',
  imageSubRegion : undefined,
  color : SuperMap3D.Color.WHITE,
  id : undefined,
  rotation : 0.0,
  alignedAxis : SuperMap3D.Cartesian3.ZERO,
  width : undefined,
  height : undefined,
  scaleByDistance : undefined,
  translucencyByDistance : undefined,
  pixelOffsetScaleByDistance : undefined,
  sizeInMeters : false,
  distanceDisplayCondition : undefined
});
// Example 2:  Specify only the billboard's cartographic position.
var b = billboards.add({
  position : SuperMap3D.Cartesian3.fromDegrees(longitude, latitude, height)
});

contains(billboard){Boolean}

Check if this collection contains the given bulletin board.

Name Type Description
billboard Billboard optional

The bulletin board to be checked.
See:
Returns:
Type Description
Boolean If this collection contains bulletin boards, it is true; otherwise, it is false.

containsByID(label){Boolean}

Check whether this collection contains a billboard by id.

Name Type Description
label Label

The label to check for.
See:
Returns:
Type Description
Boolean true if this collection contains the billboard, false otherwise.

destroy(){undefined}

Destroy the WebGL resources held by the object. Destroying an object can release WebGL resources deterministically, rather than relying on a garbage collector to destroy the object. Once the object is destroyed, it should not be used again; Calling any function other than isDestroyed will result in a Developer Error exception. Therefore, please assign the return value (undefined) to the object using the method shown in the example.

See:
Throws:

The object has been destroyed, i.e. destroy() has been called.

Type
DeveloperError
Returns:
Type Description
undefined
Example
billboards = billboards && billboards.destroy();

get(index){Billboard}

Return the bulletin board at the specified index in the collection. The index starts from 0 and increases with the increase of bulletin boards. Removing a bulletin board will move all subsequent bulletin boards to the left and change their index. This function is typically used in conjunction with BillboardCollection # length to traverse all bulletin boards in a collection.

Name Type Description
index Number

Zero based index of bulletin board.
See:
Throws:

The object is destroyed by calling destroy().

Type
DeveloperError
Returns:
Type Description
Billboard Specify the bulletin board at the index location.
Example
// Toggle the show property of every billboard in the collection
var len = billboards.length;
for (var i = 0; i < len; ++i) {
  var b = billboards.get(i);
  b.show = !b.show;
}

getVisibleInViewport(index){Boolean}

Obtain the visibility of the viewport corresponding to the layer

Name Type Description
index Number

Index
Throws:

the index is 0~8

Type
DeveloperError
Returns:
Type Description
Boolean Visible visibility

isDestroyed(){Boolean}

If the object has been destroyed, return true; Otherwise, return false. If the object has been destroyed, it should not be used; Calling any function other than isDestroyed will result in a Developer Error exception.

See:
Returns:
Type Description
Boolean If the object has been destroyed, it is true; Otherwise, it is false.

remove(billboard){Boolean}

Remove a bulletin board from the collection.

Name Type Description
billboard Billboard

The bulletin board to be removed.
See:
Throws:

The object is destroyed by calling destroy().

Type
DeveloperError
Returns:
Type Description
Boolean If the bulletin board has been removed, it is true; If the bulletin board cannot be found in the collection, it is false. Calling remove is the expected constant time. However, rewriting the vertex buffer of the set - a 0 (n) operation - also results in CPU to GPU overhead. To achieve optimal performance, remove as many bulletin boards as possible before calling update. If you want to temporarily hide a bulletin board, calling # show instead of deleting and re adding the bulletin board is usually more effective.
Example
var b = billboards.add(...);
billboards.remove(b);  // Returns true

removeAll()

Remove all bulletin boards from the collection.

Performance:

O(n)。 Deleting all bulletin boards from the collection and then adding new ones is more effective than creating a new collection entirely.

See:
Throws:

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

Type
DeveloperError
Example
billboards.add(...);
billboards.add(...);
billboards.removeAll();

setVisibleInViewport(index, visible)

Set layer corresponding viewport visibility

Name Type Description
index Number

Index
visible Boolean

visibility
Throws:

the index is 0~8

Type
DeveloperError

update()

Called when rendering the scene in Viewer or Widget to obtain the drawing instructions required to render the primitive.

Do not directly call this function. Recording this function is only to list possible exceptions that may propagate during scene rendering:

Throws:

The image with ID must be in the image set.

Type
RuntimeError