Billboard

internal constructor new Cesium.Billboard(options, billboardCollection)

engine/Source/Scene/Billboard.js 91

通过调用 BillboardCollection#add 创建广告牌并设置其初始属性。不要直接调用构造函数。

视口对齐的图像位于 3D 场景中，使用 BillboardCollection 创建和渲染。

示例广告牌

Performance:

读取属性（例如 Billboard#show）是常数时间。为属性赋值是常数时间，但在调用 BillboardCollection#update 时会产生 CPU 到 GPU 的数据传输。每个广告牌的数据传输量相同，与更新了多少属性无关。如果集合中的大多数广告牌需要更新，则使用 BillboardCollection#removeAll 清除集合并添加新广告牌可能比修改每个广告牌更高效。

Name	Type	Description
options	Billboard.ConstructorOptions	Object describing initialization options
billboardCollection	BillboardCollection	Instance of BillboardCollection

Throws:

• DeveloperError : scaleByDistance.far 必须大于 scaleByDistance.near
• DeveloperError : translucencyByDistance.far 必须大于 translucencyByDistance.near
• DeveloperError : pixelOffsetScaleByDistance.far 必须大于 pixelOffsetScaleByDistance.near
• DeveloperError : distanceDisplayCondition.far 必须大于 distanceDisplayCondition.near

Demo:

• Cesium Sandcastle Billboard Demo

See:

• BillboardCollection
• BillboardCollection#add
• Label

Members

Examples:

// 示例 1。
// 使广告牌向上向量指向北方
billboard.alignedAxis = Cesium.Cartesian3.UNIT_Z;

// 示例 2。
// 使广告牌指向东方。
billboard.alignedAxis = Cesium.Cartesian3.UNIT_Z;
billboard.rotation = -Cesium.Math.PI_OVER_TWO;

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

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

default

alpha : 0.5

红、绿、蓝和 alpha 值由 value 的 red、green、 blue 和 alpha 属性指示，如示例 1 所示。这些分量的范围是 0.0 （无强度）到 1.0（全强度）。

Examples:

// 示例 1。赋值为黄色。
b.color = Cesium.Color.YELLOW;

// 示例 2。使广告牌 50% 半透明。
b.color = new Cesium.Color(1.0, 1.0, 1.0, 0.5);

Default Value: undefined

Default Value: undefined

获取或设置应用于此广告牌的眼坐标中的 3D 笛卡尔偏移。眼坐标系是左手坐标系，其中 x 指向观察者的右侧，y 指向上方，z 指向屏幕内。眼坐标使用与世界坐标和模型坐标相同的比例，通常为米。

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

下面，广告牌位于地球中心，但眼偏移使其始终出现在地球上方，无论观察者或地球的朝向如何。

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

Default Value: HeightReference.NONE

获取或设置此广告牌的水平原点，决定广告牌位于其锚点位置的左侧、中心还是右侧。

Example:

// 使用底部、左侧原点
b.horizontalOrigin = Cesium.HorizontalOrigin.LEFT;
b.verticalOrigin = Cesium.VerticalOrigin.BOTTOM;

Example:

// 从 URL 加载图像
b.image = 'some/image/url.png';

// 假设 b1 和 b2 是同一广告牌集合中的广告牌，
// 为两个广告牌使用相同的图像。
b2.image = b1.image;

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

default

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

广告牌的原点用黄点表示。

Examples:

// 示例 1。
// 当相机距离广告牌 1500 米时，将广告牌的像素偏移缩放设置为 0.0，
// 当相机距离接近 8.0e6 米时，在 y 方向将像素偏移缩放到 10.0 像素。
b.pixelOffset = new Cesium.Cartesian2(0.0, 1.0);
b.pixelOffsetScaleByDistance = new Cesium.NearFarScalar(1.5e2, 0.0, 8.0e6, 10.0);

// 示例 2。
// 禁用按距离像素偏移
b.pixelOffsetScaleByDistance = undefined;

Default Value: false

获取或设置与广告牌图像大小（像素）相乘的统一缩放比例。 缩放比例为 1.0 时不改变广告牌大小；大于 1.0 会放大广告牌；小于 1.0 的正数会缩小广告牌。

上图从左到右的缩放比例分别为 0.5、1.0 和 2.0。

Examples:

// 示例 1。
// 当相机距离广告牌 1500 米时，将广告牌的 scaleByDistance 设置为 1.5，
// 当相机距离接近 8.0e6 米时消失。
b.scaleByDistance = new Cesium.NearFarScalar(1.5e2, 1.5, 8.0e6, 0.0);

// 示例 2。
// 禁用按距离缩放
b.scaleByDistance = undefined;

Default Value: true

Default Value: false

Default Value: SplitDirection.NONE

Examples:

// 示例 1。
// 当相机距离广告牌 1500 米时，将广告牌的半透明度设置为 1.0，
// 当相机距离接近 8.0e6 米时消失。
b.translucencyByDistance = new Cesium.NearFarScalar(1.5e2, 1.0, 8.0e6, 0.0);

// 示例 2。
// 禁用按距离半透明度
b.translucencyByDistance = undefined;

获取或设置此广告牌的垂直原点，决定广告牌位于其锚点位置的上方、下方还是中心。

Example:

// 使用底部、左侧原点
b.horizontalOrigin = Cesium.HorizontalOrigin.LEFT;
b.verticalOrigin = Cesium.VerticalOrigin.BOTTOM;

Methods

Returns:

Throws:

• DeveloperError : 广告牌必须在集合中。

Example:

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

See:

• Billboard#eyeOffset
• Billboard#pixelOffset

Returns:

Example:

// 动态创建广告牌图像
function drawImage(id) {
  // 使用 canvas 创建和绘制图像
  const canvas = document.createElement('canvas');
  const context2D = canvas.getContext('2d');
  // ... 绘制图像
  return canvas;
}
// 将调用 drawImage 来创建纹理
b.setImage('myImage', drawImage);

// 使用相同 id 在同一集合中创建的后续广告牌将使用现有
// 纹理，无需创建 canvas 或绘制图像
b2.setImage('myImage', drawImage);

Throws:

• RuntimeError : id 对应的图像必须在图集中

Type Definitions

Properties:

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

Returns: