KBE3D / KBCore / Cesium / BillboardCollection

类: BillboardCollection

A renderable collection of billboards. Billboards are viewport-aligned images positioned in the 3D scene. <br /><br /> <div align='center'> <img src='/Images/Billboard.png' width='400' height='300' /><br /> Example billboards </div> <br /><br /> Billboards are added and removed from the collection using BillboardCollection#add and BillboardCollection#remove. Billboards in a collection automatically share textures for images with the same identifier.

示例

// Create a billboard collection with two billboards
const billboards = scene.primitives.add(new Cesium.BillboardCollection());
billboards.add({
  position : new Cesium.Cartesian3(1.0, 2.0, 3.0),
  image : 'url/to/image'
});
billboards.add({
  position : new Cesium.Cartesian3(4.0, 5.0, 6.0),
  image : 'url/to/another/image'
});

参数

Object with the following properties:

参数

The 4x4 transformation matrix that transforms each billboard from model to world coordinates.

参数

For debugging only. Determines if this primitive's commands' bounding spheres are shown.

参数

Must be passed in for billboards that use the height reference property or will be depth tested against the globe.

参数

The billboard blending option. The default is used for rendering both opaque and translucent billboards. However, if either all of the billboards are completely opaque or all are completely translucent, setting the technique to BlendOption.OPAQUE or BlendOption.TRANSLUCENT can improve performance by up to 2x.

参数

Determines if the billboards in the collection will be shown.

参数

The distance from the camera, beyond which, billboards are depth-tested against an approximation of the globe ellipsoid rather than against the full globe depth buffer. If unspecified, the default value is determined relative to the value of Ellipsoid.default.

参数

The distance from the camera, within which, billboards with a Billboard#heightReference value of HeightReference.CLAMP_TO_GROUND or HeightReference.CLAMP_TO_TERRAIN are depth tested against three key points. This ensures that if any key point of the billboard is visible, the whole billboard will be visible. If unspecified, the default value is determined relative to the value of Ellipsoid.default.

属性

show

show: boolean

Determines if billboards in this collection will be shown.

---

modelMatrix

modelMatrix: Matrix4

The 4x4 transformation matrix that transforms each billboard in this collection from model to world coordinates. When this is the identity matrix, the billboards are drawn in world coordinates, i.e., Earth's WGS84 coordinates. Local reference frames can be used by providing a different transformation matrix, like that returned by Transforms.eastNorthUpToFixedFrame.

示例

const center = Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883);
billboards.modelMatrix = Cesium.Transforms.eastNorthUpToFixedFrame(center);
billboards.add({
  image : 'url/to/image',
  position : new Cesium.Cartesian3(0.0, 0.0, 0.0) // center
});
billboards.add({
  image : 'url/to/image',
  position : new Cesium.Cartesian3(1000000.0, 0.0, 0.0) // east
});
billboards.add({
  image : 'url/to/image',
  position : new Cesium.Cartesian3(0.0, 1000000.0, 0.0) // north
});
billboards.add({
  image : 'url/to/image',
  position : new Cesium.Cartesian3(0.0, 0.0, 1000000.0) // up
});

---

debugShowBoundingVolume

debugShowBoundingVolume: boolean

This property is for debugging only; it is not for production use nor is it optimized. <p> Draws the bounding sphere for each draw command in the primitive. </p>

---

debugShowTextureAtlas

debugShowTextureAtlas: boolean

This property is for debugging only; it is not for production use nor is it optimized. <p> Draws the texture atlas for this BillboardCollection as a fullscreen quad. </p>

---

blendOption

blendOption: BlendOption

The billboard blending option. The default is used for rendering both opaque and translucent billboards. However, if either all of the billboards are completely opaque or all are completely translucent, setting the technique to BlendOption.OPAQUE or BlendOption.TRANSLUCENT can improve performance by up to 2x.

---

length

readonly length: number

Returns the number of billboards in this collection. This is commonly used with BillboardCollection#get to iterate over all the billboards in the collection.

---

coarseDepthTestDistance

coarseDepthTestDistance: number

The distance from the camera, beyond which, billboards are depth-tested against an approximation of the globe ellipsoid rather than against the full globe depth buffer. When set to <code>0</code>, the approximate depth test is always applied. When set to <code>Number.POSITIVE_INFINITY</code>, the approximate depth test is never applied. <br/><br/> This setting only applies when a billboard's Billboard#disableDepthTestDistance value would otherwise allow depth testing—i.e., distance from the camera to the billboard is less than a billboard's Billboard#disableDepthTestDistance value.

---

threePointDepthTestDistance

threePointDepthTestDistance: number

The distance from the camera, within which, billboards with a Billboard#heightReference value of HeightReference.CLAMP_TO_GROUND or HeightReference.CLAMP_TO_TERRAIN are depth tested against three key points. This ensures that if any key point of the billboard is visible, the whole billboard will be visible. When set to <code>0</code>, this feature is disabled and portions of a billboards behind terrain be clipped. <br/><br/> This setting only applies when a billboard's Billboard#disableDepthTestDistance value would otherwise allow depth testing—i.e., distance from the camera to the billboard is less than a billboard's Billboard#disableDepthTestDistance value.

方法

add()

add(options?: ConstructorOptions): Billboard

Creates and adds a billboard with the specified initial properties to the collection. The added billboard is returned so it can be modified or removed from the collection later.

参数

options?

ConstructorOptions

A template describing the billboard's properties as shown in Example 1.

返回

Billboard

The billboard that was added to the collection.

Examples

// Example 1:  Add a billboard, specifying all the default values.
const b = billboards.add({
  show : true,
  position : Cesium.Cartesian3.ZERO,
  pixelOffset : Cesium.Cartesian2.ZERO,
  eyeOffset : Cesium.Cartesian3.ZERO,
  heightReference : Cesium.HeightReference.NONE,
  horizontalOrigin : Cesium.HorizontalOrigin.CENTER,
  verticalOrigin : Cesium.VerticalOrigin.CENTER,
  scale : 1.0,
  image : 'url/to/image',
  imageSubRegion : undefined,
  color : Cesium.Color.WHITE,
  id : undefined,
  rotation : 0.0,
  alignedAxis : Cesium.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.
const b = billboards.add({
  position : Cesium.Cartesian3.fromDegrees(longitude, latitude, height)
});

---

remove()

remove(billboard: Billboard): boolean

Removes a billboard from the collection.

参数

billboard

Billboard

The billboard to remove.

返回

boolean

true if the billboard was removed; false if the billboard was not found in the collection.

示例

const b = billboards.add(...);
billboards.remove(b);  // Returns true

---

removeAll()

removeAll(): void

Removes all billboards from the collection.

返回

void

示例

billboards.add(...);
billboards.add(...);
billboards.removeAll();

---

contains()

contains(billboard?: Billboard): boolean

Check whether this collection contains a given billboard.

参数

billboard?

Billboard

The billboard to check for.

返回

boolean

true if this collection contains the billboard, false otherwise.

---

get()

get(index: number): Billboard

Returns the billboard in the collection at the specified index. Indices are zero-based and increase as billboards are added. Removing a billboard shifts all billboards after it to the left, changing their indices. This function is commonly used with BillboardCollection#length to iterate over all the billboards in the collection.

参数

index

number

The zero-based index of the billboard.

返回

Billboard

The billboard at the specified index.

示例

// Toggle the show property of every billboard in the collection
const len = billboards.length;
for (let i = 0; i < len; ++i) {
  const b = billboards.get(i);
  b.show = !b.show;
}

---

update()

update(): void

Called when Viewer or CesiumWidget render the scene to get the draw commands needed to render this primitive. <p> Do not call this function directly. This is documented just to list the exceptions that may be propagated when the scene is rendered: </p>

返回

void

---

isDestroyed()

isDestroyed(): boolean

Returns true if this object was destroyed; otherwise, false. <br /><br /> If this object was destroyed, it should not be used; calling any function other than <code>isDestroyed</code> will result in a DeveloperError exception.

返回

boolean

true if this object was destroyed; otherwise, false.

---

destroy()

destroy(): void

Destroys the WebGL resources held by this object. Destroying an object allows for deterministic release of WebGL resources, instead of relying on the garbage collector to destroy this object. <br /><br /> Once an object is destroyed, it should not be used; calling any function other than <code>isDestroyed</code> will result in a DeveloperError exception. Therefore, assign the return value (<code>undefined</code>) to the object as done in the example.

返回

void

示例

billboards = billboards && billboards.destroy();

构造函数

构造函数

new BillboardCollection(options?: { modelMatrix?: Matrix4; debugShowBoundingVolume?: boolean; scene?: Scene; blendOption?: BlendOption; show?: boolean; coarseDepthTestDistance?: number; threePointDepthTestDistance?: number; }): BillboardCollection

参数

options?

modelMatrix?

Matrix4

debugShowBoundingVolume?

boolean

scene?

Scene

blendOption?

BlendOption

show?

boolean

coarseDepthTestDistance?

number

threePointDepthTestDistance?

number

返回

BillboardCollection