Billboard

internal constructor new Cesium.Billboard(options, billboardCollection)

engine/Source/Scene/Billboard.js 95

将创建一个公告板，其初始 属性通过调用BillboardCollection#add. 不要直接调用构造函数。

位于 3D 场景中的与视口对齐的图像，该图像是创建的 并使用 BillboardCollection 进行渲染。

广告牌示例

Performance:

读取属性(例如 Billboard#show)是恒定时间。 分配给属性是恒定时间，但会导致 调用 BillboardCollection#update 时的 CPU 到 GPU 流量。 每个公告牌的流量为 无论更新了多少个属性，都是相同的。 如果集合中的大多数广告牌都需要 更新，使用 BillboardCollection#removeAll 清除收藏可能会更有效。 并添加新的广告牌，而不是修改每个广告牌。

Name	Type	Description
options	Billboard.ConstructorOptions	描述初始化选项的对象
billboardCollection	BillboardCollection	Instance of BillboardCollection

Throws:

• DeveloperError : scaleByDistance.far must be greater than scaleByDistance.near
• DeveloperError : translucencyByDistance.far must be greater than translucencyByDistance.near
• DeveloperError : pixelOffsetScaleByDistance.far must be greater than pixelOffsetScaleByDistance.near
• DeveloperError : distanceDisplayCondition.far must be greater than distanceDisplayCondition.near

Demo:

• Cesium Sandcastle Billboard Demo

See:

• BillboardCollection
• BillboardCollection#add
• Label

Members

Examples:

// Example 1.
// Have the billboard up vector point north
billboard.alignedAxis = Cesium.Cartesian3.UNIT_Z;

// Example 2.
// Have the billboard point east.
billboard.alignedAxis = Cesium.Cartesian3.UNIT_Z;
billboard.rotation = -Cesium.Math.PI_OVER_TWO;

// Example 3.
// Reset the aligned axis
billboard.alignedAxis = Cesium.Cartesian3.ZERO;

获取或设置与 Billboard 的纹理相乘的颜色。 这有两个常见的用例。 第一 相同的白色纹理可以被许多不同的广告牌使用，每个广告牌都有不同的颜色，以创建 彩色广告牌。 其次，颜色的 Alpha 分量可用于使公告牌半透明，如下所示。 Alpha 值为 0.0 时，广告牌透明，Alpha 值为 1.0 时，广告牌不透明。

default

alpha : 0.5

红色、绿色、蓝色和 alpha 值由值的 red、green、 blue 和 alpha 属性，如示例 1 所示。 这些组件的范围从 0.0 (无强度)到 1.0(全强度)。

Examples:

// Example 1. Assign yellow.
b.color = Cesium.Color.YELLOW;

// Example 2. Make a billboard 50% translucent.
b.color = new Cesium.Color(1.0, 1.0, 1.0, 0.5);

Default Value: undefined

获取或设置在眼睛坐标中应用于此广告牌的 3D 笛卡尔偏移。 眼睛坐标是左撇子 坐标系，其中 x 指向查看器的右侧，y 指向上方，并且 z 指向屏幕。 眼睛坐标使用与世界和模型坐标相同的比例。 通常为 meters。

眼动偏移通常用于将多个广告牌或对象排列在同一位置，例如，将 在其相应的 3D 模型上方布置广告牌。

在下面，广告牌位于地球的中心，但眼睛偏移使其始终 显示在地球顶部，无论观看者或地球的方向如何。

b.eyeOffset = new Cartesian3(0.0, 8000000.0, 0.0);

Default Value: HeightReference.NONE

获取或设置此公告板的水平原点，用于确定公告板是否为 拖动到其锚点位置的左侧、中间或右侧。

Example:

// Use a bottom, left origin
b.horizontalOrigin = Cesium.HorizontalOrigin.LEFT;
b.verticalOrigin = Cesium.VerticalOrigin.BOTTOM;

Example:

// load an image from a URL
b.image = 'some/image/url.png';

// assuming b1 and b2 are billboards in the same billboard collection,
// use the same image for both billboards.
b2.image = b1.image;

获取或设置屏幕空间中与此公告牌原点的像素偏移。 这是常用的 将多个广告牌和标签对齐在同一位置，例如，图像和文本。 这 屏幕空间原点是画布的左上角;x 从 从左到右，y 从上到下增加。

default

b.pixeloffset = new Cartesian2(50, 25);

公告牌的原点由黄点表示。

Examples:

// Example 1.
// Set a billboard's pixel offset scale to 0.0 when the
// camera is 1500 meters from the billboard and scale pixel offset to 10.0 pixels
// in the y direction the camera distance approaches 8.0e6 meters.
b.pixelOffset = new Cesium.Cartesian2(0.0, 1.0);
b.pixelOffsetScaleByDistance = new Cesium.NearFarScalar(1.5e2, 0.0, 8.0e6, 10.0);

// Example 2.
// disable pixel offset by distance
b.pixelOffsetScaleByDistance = undefined;

Default Value: false

获取或设置Uniform Scale (均匀缩放)，乘以公告牌的图像大小(以像素为单位)。 1.0 的比例不会改变广告牌的大小;大于 1.0 放大广告牌;小于 1.0 的正比例会收缩 广告牌。

在上图中，比例尺从左到右依次为 0.5, 1.0, 和 2.0.

Examples:

// Example 1.
// Set a billboard's scaleByDistance to scale by 1.5 when the
// camera is 1500 meters from the billboard and disappear as
// the camera distance approaches 8.0e6 meters.
b.scaleByDistance = new Cesium.NearFarScalar(1.5e2, 1.5, 8.0e6, 0.0);

// Example 2.
// disable scaling by distance
b.scaleByDistance = undefined;

Default Value: true

Default Value: false

Default Value: SplitDirection.NONE

Examples:

// Example 1.
// Set a billboard's translucency to 1.0 when the
// camera is 1500 meters from the billboard and disappear as
// the camera distance approaches 8.0e6 meters.
b.translucencyByDistance = new Cesium.NearFarScalar(1.5e2, 1.0, 8.0e6, 0.0);

// Example 2.
// disable translucency by distance
b.translucencyByDistance = undefined;

获取或设置此公告板的垂直原点，用于确定公告板是否为 拖动到其锚点位置的上方、下方或中心。

Example:

// Use a bottom, left origin
b.horizontalOrigin = Cesium.HorizontalOrigin.LEFT;
b.verticalOrigin = Cesium.VerticalOrigin.BOTTOM;

Methods

Returns:

Throws:

• DeveloperError : Billboard must be in a collection.

Example:

console.log(b.computeScreenSpacePosition(scene).toString());

See:

• Billboard#eyeOffset
• Billboard#pixelOffset

Returns:

Example:

// create a billboard image dynamically
function drawImage(id) {
  // create and draw an image using a canvas
  const canvas = document.createElement('canvas');
  const context2D = canvas.getContext('2d');
  // ... draw image
  return canvas;
}
// drawImage will be called to create the texture
b.setImage('myImage', drawImage);

// subsequent billboards created in the same collection using the same id will use the existing
// texture, without the need to create the canvas or draw the image
b2.setImage('myImage', drawImage);

Throws:

• RuntimeError : image with id must be in the atlas

Type Definitions

Properties:

Name	Type	Attributes	Default	Description
position	Cartesian3			广告牌的笛卡尔位置。
id	*	<optional>		使用 Scene#pick 选取公告牌时返回的用户定义对象。
show	boolean	<optional>	true	确定是否显示此公告板。
image	string | HTMLCanvasElement	<optional>		一个加载的 HTMLImageElement、ImageData 或用于广告牌的图像的 URL。
scale	number	<optional>	1.0	一个数字，用于指定均匀缩放比例，该比例乘以公告牌的图像大小(以像素为单位)。
pixelOffset	Cartesian2	<optional>	Cartesian2.ZERO	A Cartesian2 指定屏幕空间中与此广告牌原点的像素偏移量。
eyeOffset	Cartesian3	<optional>	Cartesian3.ZERO	A Cartesian3 指定在眼坐标中应用于此广告牌的 3D 笛卡尔偏移量。
horizontalOrigin	HorizontalOrigin	<optional>	HorizontalOrigin.CENTER	A HorizontalOrigin 指定此广告牌的水平原点。
verticalOrigin	VerticalOrigin	<optional>	VerticalOrigin.CENTER	A VerticalOrigin 指定此广告牌的垂直原点。
heightReference	HeightReference	<optional>	HeightReference.NONE	A HeightReference 指定此公告牌的高度参考。
color	Color	<optional>	Color.WHITE	A Color 指定与公告牌纹理相乘的颜色。
rotation	number	<optional>	0	一个数字，指定以弧度为单位的旋转角度。
alignedAxis	Cartesian3	<optional>	Cartesian3.ZERO	A Cartesian3 指定世界空间中对齐的轴。
sizeInMeters	boolean	<optional>		一个布尔值，指定广告牌的大小是以米为单位还是以像素为单位。
width	number	<optional>		指定公告牌宽度的数字。如果未定义，则将使用图像宽度。
height	number	<optional>		指定公告牌高度的数字。如果未定义，则将使用图像高度。
scaleByDistance	NearFarScalar	<optional>		A NearFarScalar 根据公告牌与摄像机的距离指定公告牌的近距和远距缩放属性。
translucencyByDistance	NearFarScalar	<optional>		A NearFarScalar 根据公告牌与摄像机的距离指定公告牌的近距和远距半透明属性。
pixelOffsetScaleByDistance	NearFarScalar	<optional>		A NearFarScalar 根据公告牌与摄像机的距离指定公告牌的近距和远距像素偏移缩放属性。
imageSubRegion	BoundingRectangle	<optional>		A BoundingRectangle 指定要用于公告牌的图像子区域，而不是整个图像。
distanceDisplayCondition	DistanceDisplayCondition	<optional>		A DistanceDisplayCondition 指定显示此公告牌的摄像机的距离。
disableDepthTestDistance	number	<optional>		一个数字，用于指定与摄像机的距离，在该距离处禁用深度测试，例如，防止针对地形进行裁剪。
splitDirection	SplitDirection	<optional>		A SplitDirection 指定公告牌的 split 属性。

Returns: