Class: BillboardCollection

BillboardCollection

new BillboardCollection()

可渲染的布告板集合。


Example billboards
布告板可通过 BillboardCollection#add 和 BillboardCollection#remove 从集合中添加和移除。集合中的布告板会自动共享具有相同标识符的影像纹理。
Name Type Default Description
options.modelMatrix Matrix4 Matrix4.IDENTITY 可选

4x4 变换矩阵，用于将每个布告板从模型变换到地理坐标。
options.debugShowBoundingVolume Boolean false 可选

仅用于调试。确定是否显示该基元的命令包围球。
options.scene Scene 可选

对于使用高度参考属性的布告板或将根据地球进行深度测试的布告板，必须输入该参数。
options.blendOption BlendOption BlendOption.OPAQUE_AND_TRANSLUCENT 可选

布告板混合选项。默认用于渲染不透明和半透明的布告板。 然而，如果所有的布告板都是完全不透明的或完全半透明的，将技术设置为BillboardRenderTechnique。 OPAQUE或BillboardRenderTechnique。半透明可以将性能提高2倍。
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

布告板混合选项。默认值用于渲染不透明和半透明的布告板。 不过，如果所有布告板都是完全不透明或完全半透明的，将该技术设置为 BillboardRenderTechnique.OPAQUE 或 BillboardRenderTechnique.TRANSLUCENT 最多可将性能提高 2 倍。

Default Value:
BlendOption.OPAQUE_AND_TRANSLUCENT

debugShowBoundingVolumeBoolean

此属性仅用于调试 为基元中的每个绘制命令绘制包围球。

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

返回此集合中布告板的数量。通常与BillboardCollection#get一起使用，以遍历集合中的所有布告板。

modelMatrixMatrix4

4x4变换矩阵，将这个集合中的每个布告板从模型转换为地理坐标。当这是单位矩阵时，布告板以地理坐标绘制，即WGS84坐标。 本地参考帧可以通过提供不同的转换矩阵来使用，就像Transforms.eastNorthUpToFixedFrame返回的那样。

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}

创建一个具有指定初始属性的布告板并将其添加到集合中。添加的布告板将被返回，以便以后修改或从集合中删除。

Name Type Description
billboard Object 可选

描述布告板属性的模板，如例 1 所示。
See:
Throws:

该对象被销毁，即调用destroy()。

Type
DeveloperError
Returns:
Type Description
Billboard 加入该系列的布告板。 调用add是期望的常数时间。 然而，集合的顶点缓冲区被重写一个 0 (n)操作，也会导致CPU到GPU的开销。 为了获得最佳性能，在调用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}

检查此集合是否包含给定的布告板。

Name Type Description
billboard Billboard 可选

要检查的布告板。
See:
Returns:
Type Description
Boolean 如果此集合包含布告板，则为True，否则为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}

销毁该对象持有的 WebGL 资源。销毁对象可以确定性地释放 WebGL 资源，而不是依赖垃圾回收器来销毁该对象。

一旦对象被销毁，就不应再使用；调用 isDestroyed 以外的任何函数都将导致 DeveloperError 异常。因此，请按照示例中的方法将返回值（undefined）赋值给对象。

See:
Throws:

该对象已被销毁，即 destroy() 被调用。

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

get(index){Billboard}

返回集合中指定索引处的布告板。指数从0开始，随着布告板的增加而增加。 移除一个布告板会将它之后的所有布告板移到左侧，改变它们的索引。 此函数通常与BillboardCollection#length一起使用，用于遍历集合中的所有布告板。

Name Type Description
index Number

布告板的零基索引。
See:
Throws:

该对象被销毁，即调用destroy()。

Type
DeveloperError
Returns:
Type Description
Billboard 指定索引处的布告板。
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}

获得图层对应视口可见性

Name Type Description
index Number

索引
Throws:

the index is 0~8

Type
DeveloperError
Returns:
Type Description
Boolean visible 可见性

isDestroyed(){Boolean}

如果该对象已被销毁，则返回 true；否则返回 false。

如果该对象已被销毁，则不应使用；调用 isDestroyed 以外的任何函数都将导致 DeveloperError 异常。

See:
Returns:
Type Description
Boolean 如果该对象已销毁，则为 true；否则为 false。

remove(billboard){Boolean}

从集合中移除一个布告板。

Name Type Description
billboard Billboard

要移除的布告板。
See:
Throws:

该对象被销毁，即调用destroy()。

Type
DeveloperError
Returns:
Type Description
Boolean 如果布告板已被移除，则为 true；如果在集合中找不到该布告板，则为 false。 调用remove是期望的常量时间。然而，集合的顶点缓冲区被重写——一个 0 (n)操作，也会导致CPU到GPU的开销。 为了获得最佳性能，在调用update之前尽可能多地移除布告板。 如果你想暂时隐藏一个布告板，调用#show而不是删除并重新添加布告板通常更有效。
Example
var b = billboards.add(...);
billboards.remove(b);  // Returns true

removeAll()

从集合中移除所有布告板。

Performance:

O(n)。从集合中删除所有布告板，然后添加新布告板比完全创建一个新集合更有效。

See:
Throws:

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

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

setVisibleInViewport(index, visible)

设置图层对应视口可见性

Name Type Description
index Number

索引
visible Boolean

可见性
Throws:

the index is 0~8

Type
DeveloperError

update()

在Viewer 或 Widget 渲染场景时调用，以获取渲染该基元所需的绘制指令。

请勿直接调用此函数。记录此函数只是为了列出场景渲染时可能传播的异常：

Throws:

带 id 的影像必须在图集中。

Type
RuntimeError