import defaultValue from '../Core/defaultValue.js';
import defined from '../Core/defined.js';
import defineProperties from '../Core/defineProperties.js';
import DeveloperError from '../Core/DeveloperError.js';
import Event from '../Core/Event.js';
import createPropertyDescriptor from './createPropertyDescriptor.js';
/**
* Describes a two dimensional label located at the position of the containing {@link Entity}.
*
*
*

* Example labels
*
*
*
* @alias LabelGraphics
* @constructor
*
* @param {Object} [options] Object with the following properties:
* @param {Property} [options.show=true] A boolean Property specifying the visibility of the label.
* @param {Property} [options.text] A Property specifying the text. Explicit newlines '\n' are supported.
* @param {Property} [options.font='30px sans-serif'] A Property specifying the CSS font.
* @param {Property} [options.style=LabelStyle.FILL] A Property specifying the {@link LabelStyle}.
* @param {Property} [options.scale=1.0] A numeric Property specifying the scale to apply to the text.
* @param {Property} [options.showBackground=false] A boolean Property specifying the visibility of the background behind the label.
* @param {Property} [options.backgroundColor=new Color(0.165, 0.165, 0.165, 0.8)] A Property specifying the background {@link Color}.
* @param {Property} [options.backgroundPadding=new Cartesian2(7, 5)] A {@link Cartesian2} Property specifying the horizontal and vertical background padding in pixels.
* @param {Property} [options.pixelOffset=Cartesian2.ZERO] A {@link Cartesian2} Property specifying the pixel offset.
* @param {Property} [options.eyeOffset=Cartesian3.ZERO] A {@link Cartesian3} Property specifying the eye offset.
* @param {Property} [options.horizontalOrigin=HorizontalOrigin.CENTER] A Property specifying the {@link HorizontalOrigin}.
* @param {Property} [options.verticalOrigin=VerticalOrigin.CENTER] A Property specifying the {@link VerticalOrigin}.
* @param {Property} [options.heightReference=HeightReference.NONE] A Property specifying what the height is relative to.
* @param {Property} [options.fillColor=Color.WHITE] A Property specifying the fill {@link Color}.
* @param {Property} [options.outlineColor=Color.BLACK] A Property specifying the outline {@link Color}.
* @param {Property} [options.outlineWidth=1.0] A numeric Property specifying the outline width.
* @param {Property} [options.translucencyByDistance] A {@link NearFarScalar} Property used to set translucency based on distance from the camera.
* @param {Property} [options.pixelOffsetScaleByDistance] A {@link NearFarScalar} Property used to set pixelOffset based on distance from the camera.
* @param {Property} [options.scaleByDistance] A {@link NearFarScalar} Property used to set scale based on distance from the camera.
* @param {Property} [options.distanceDisplayCondition] A Property specifying at what distance from the camera that this label will be displayed.
* @param {Property} [options.disableDepthTestDistance] A Property specifying the distance from the camera at which to disable the depth test to.
*
* @demo {@link https://sandcastle.cesium.com/index.html?src=Labels.html|Cesium Sandcastle Labels Demo}
*/
function LabelGraphics(options) {
this._definitionChanged = new Event();
this._show = undefined;
this._showSubscription = undefined;
this._text = undefined;
this._textSubscription = undefined;
this._font = undefined;
this._fontSubscription = undefined;
this._style = undefined;
this._styleSubscription = undefined;
this._scale = undefined;
this._scaleSubscription = undefined;
this._showBackground = undefined;
this._showBackgroundSubscription = undefined;
this._backgroundColor = undefined;
this._backgroundColorSubscription = undefined;
this._backgroundPadding = undefined;
this._backgroundPaddingSubscription = undefined;
this._pixelOffset = undefined;
this._pixelOffsetSubscription = undefined;
this._eyeOffset = undefined;
this._eyeOffsetSubscription = undefined;
this._horizontalOrigin = undefined;
this._horizontalOriginSubscription = undefined;
this._verticalOrigin = undefined;
this._verticalOriginSubscription = undefined;
this._heightReference = undefined;
this._heightReferenceSubscription = undefined;
this._fillColor = undefined;
this._fillColorSubscription = undefined;
this._outlineColor = undefined;
this._outlineColorSubscription = undefined;
this._outlineWidth = undefined;
this._outlineWidthSubscription = undefined;
this._translucencyByDistance = undefined;
this._translucencyByDistanceSubscription = undefined;
this._pixelOffsetScaleByDistance = undefined;
this._pixelOffsetScaleByDistanceSubscription = undefined;
this._scaleByDistance = undefined;
this._scaleByDistanceSubscription = undefined;
this._distanceDisplayCondition = undefined;
this._distanceDisplayConditionSubscription = undefined;
this._disableDepthTestDistance = undefined;
this._disableDepthTestDistanceSubscription = undefined;
this.merge(defaultValue(options, defaultValue.EMPTY_OBJECT));
}
defineProperties(LabelGraphics.prototype, {
/**
* Gets the event that is raised whenever a property or sub-property is changed or modified.
* @memberof LabelGraphics.prototype
*
* @type {Event}
* @readonly
*/
definitionChanged : {
get : function() {
return this._definitionChanged;
}
},
/**
* Gets or sets the boolean Property specifying the visibility of the label.
* @memberof LabelGraphics.prototype
* @type {Property}
*/
show : createPropertyDescriptor('show'),
/**
* Gets or sets the string Property specifying the text of the label.
* Explicit newlines '\n' are supported.
* @memberof LabelGraphics.prototype
* @type {Property}
*/
text : createPropertyDescriptor('text'),
/**
* Gets or sets the string Property specifying the font in CSS syntax.
* @memberof LabelGraphics.prototype
* @type {Property}
* @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/font|CSS font on MDN}
*/
font : createPropertyDescriptor('font'),
/**
* Gets or sets the Property specifying the {@link LabelStyle}.
* @memberof LabelGraphics.prototype
* @type {Property}
*/
style : createPropertyDescriptor('style'),
/**
* Gets or sets the numeric Property specifying the uniform scale to apply to the image.
* A scale greater than 1.0
enlarges the label while a scale less than 1.0
shrinks it.
*
*
*

* From left to right in the above image, the scales are
0.5
,
1.0
,
* and
2.0
.
*
*
* @memberof LabelGraphics.prototype
* @type {Property}
* @default 1.0
*/
scale : createPropertyDescriptor('scale'),
/**
* Gets or sets the boolean Property specifying the visibility of the background behind the label.
* @memberof LabelGraphics.prototype
* @type {Property}
* @default false
*/
showBackground : createPropertyDescriptor('showBackground'),
/**
* Gets or sets the Property specifying the background {@link Color}.
* @memberof LabelGraphics.prototype
* @type {Property}
* @default new Color(0.165, 0.165, 0.165, 0.8)
*/
backgroundColor : createPropertyDescriptor('backgroundColor'),
/**
* Gets or sets the {@link Cartesian2} Property specifying the label's horizontal and vertical
* background padding in pixels.
* @memberof LabelGraphics.prototype
* @type {Property}
* @default new Cartesian2(7, 5)
*/
backgroundPadding : createPropertyDescriptor('backgroundPadding'),
/**
* Gets or sets the {@link Cartesian2} Property specifying the label's pixel offset in screen space
* from the origin of this label. This is commonly used to align multiple labels and labels at
* the same position, e.g., an image and text. The screen space origin is the top, left corner of the
* canvas; x
increases from left to right, and y
increases from top to bottom.
*
*
*
* default
 |
* l.pixeloffset = new Cartesian2(25, 75);
 |
*
* The label's origin is indicated by the yellow point.
*
*
* @memberof LabelGraphics.prototype
* @type {Property}
* @default Cartesian2.ZERO
*/
pixelOffset : createPropertyDescriptor('pixelOffset'),
/**
* Gets or sets the {@link Cartesian3} Property specifying the label's offset in eye coordinates.
* Eye coordinates is a left-handed coordinate system, where x
points towards the viewer's
* right, y
points up, and z
points into the screen.
*
* An eye offset is commonly used to arrange multiple labels or objects at the same position, e.g., to
* arrange a label above its corresponding 3D model.
*
* Below, the label is positioned at the center of the Earth but an eye offset makes it always
* appear on top of the Earth regardless of the viewer's or Earth's orientation.
*
*
*
*  |
*  |
*
*
l.eyeOffset = new Cartesian3(0.0, 8000000.0, 0.0);
*
*
* @memberof LabelGraphics.prototype
* @type {Property}
* @default Cartesian3.ZERO
*/
eyeOffset : createPropertyDescriptor('eyeOffset'),
/**
* Gets or sets the Property specifying the {@link HorizontalOrigin}.
* @memberof LabelGraphics.prototype
* @type {Property}
*/
horizontalOrigin : createPropertyDescriptor('horizontalOrigin'),
/**
* Gets or sets the Property specifying the {@link VerticalOrigin}.
* @memberof LabelGraphics.prototype
* @type {Property}
*/
verticalOrigin : createPropertyDescriptor('verticalOrigin'),
/**
* Gets or sets the Property specifying the {@link HeightReference}.
* @memberof LabelGraphics.prototype
* @type {Property}
* @default HeightReference.NONE
*/
heightReference : createPropertyDescriptor('heightReference'),
/**
* Gets or sets the Property specifying the fill {@link Color}.
* @memberof LabelGraphics.prototype
* @type {Property}
*/
fillColor : createPropertyDescriptor('fillColor'),
/**
* Gets or sets the Property specifying the outline {@link Color}.
* @memberof LabelGraphics.prototype
* @type {Property}
*/
outlineColor : createPropertyDescriptor('outlineColor'),
/**
* Gets or sets the numeric Property specifying the outline width.
* @memberof LabelGraphics.prototype
* @type {Property}
*/
outlineWidth : createPropertyDescriptor('outlineWidth'),
/**
* Gets or sets {@link NearFarScalar} Property specifying the translucency of the label based on the distance from the camera.
* A label's translucency will interpolate between the {@link NearFarScalar#nearValue} and
* {@link NearFarScalar#farValue} while the camera distance falls within the upper and lower bounds
* of the specified {@link NearFarScalar#near} and {@link NearFarScalar#far}.
* Outside of these ranges the label's translucency remains clamped to the nearest bound.
* @memberof LabelGraphics.prototype
* @type {Property}
*/
translucencyByDistance : createPropertyDescriptor('translucencyByDistance'),
/**
* Gets or sets {@link NearFarScalar} Property specifying the pixel offset of the label based on the distance from the camera.
* A label's pixel offset will interpolate between the {@link NearFarScalar#nearValue} and
* {@link NearFarScalar#farValue} while the camera distance falls within the upper and lower bounds
* of the specified {@link NearFarScalar#near} and {@link NearFarScalar#far}.
* Outside of these ranges the label's pixel offset remains clamped to the nearest bound.
* @memberof LabelGraphics.prototype
* @type {Property}
*/
pixelOffsetScaleByDistance : createPropertyDescriptor('pixelOffsetScaleByDistance'),
/**
* Gets or sets near and far scaling properties of a Label based on the label's distance from the camera.
* A label's scale will interpolate between the {@link NearFarScalar#nearValue} and
* {@link NearFarScalar#farValue} while the camera distance falls within the upper and lower bounds
* of the specified {@link NearFarScalar#near} and {@link NearFarScalar#far}.
* Outside of these ranges the label's scale remains clamped to the nearest bound. If undefined,
* scaleByDistance will be disabled.
* @memberof LabelGraphics.prototype
* @type {Property}
*/
scaleByDistance : createPropertyDescriptor('scaleByDistance'),
/**
* Gets or sets the {@link DistanceDisplayCondition} Property specifying at what distance from the camera that this label will be displayed.
* @memberof LabelGraphics.prototype
* @type {Property}
*/
distanceDisplayCondition : createPropertyDescriptor('distanceDisplayCondition'),
/**
* Gets or sets the distance from the camera at which to disable the depth test to, for example, prevent clipping against terrain.
* When set to zero, the depth test is always applied. When set to Number.POSITIVE_INFINITY, the depth test is never applied.
* @memberof LabelGraphics.prototype
* @type {Property}
*/
disableDepthTestDistance : createPropertyDescriptor('disableDepthTestDistance')
});
/**
* Duplicates this instance.
*
* @param {LabelGraphics} [result] The object onto which to store the result.
* @returns {LabelGraphics} The modified result parameter or a new instance if one was not provided.
*/
LabelGraphics.prototype.clone = function(result) {
if (!defined(result)) {
return new LabelGraphics(this);
}
result.show = this.show;
result.text = this.text;
result.font = this.font;
result.style = this.style;
result.scale = this.scale;
result.showBackground = this.showBackground;
result.backgroundColor = this.backgroundColor;
result.backgroundPadding = this.backgroundPadding;
result.pixelOffset = this.pixelOffset;
result.eyeOffset = this.eyeOffset;
result.horizontalOrigin = this.horizontalOrigin;
result.verticalOrigin = this.verticalOrigin;
result.heightReference = this.heightReference;
result.fillColor = this.fillColor;
result.outlineColor = this.outlineColor;
result.outlineWidth = this.outlineWidth;
result.translucencyByDistance = this.translucencyByDistance;
result.pixelOffsetScaleByDistance = this.pixelOffsetScaleByDistance;
result.scaleByDistance = this.scaleByDistance;
result.distanceDisplayCondition = this.distanceDisplayCondition;
result.disableDepthTestDistance = this.disableDepthTestDistance;
return result;
};
/**
* Assigns each unassigned property on this object to the value
* of the same property on the provided source object.
*
* @param {LabelGraphics} source The object to be merged into this object.
*/
LabelGraphics.prototype.merge = function(source) {
//>>includeStart('debug', pragmas.debug);
if (!defined(source)) {
throw new DeveloperError('source is required.');
}
//>>includeEnd('debug');
this.show = defaultValue(this.show, source.show);
this.text = defaultValue(this.text, source.text);
this.font = defaultValue(this.font, source.font);
this.style = defaultValue(this.style, source.style);
this.scale = defaultValue(this.scale, source.scale);
this.showBackground = defaultValue(this.showBackground, source.showBackground);
this.backgroundColor = defaultValue(this.backgroundColor, source.backgroundColor);
this.backgroundPadding = defaultValue(this.backgroundPadding, source.backgroundPadding);
this.pixelOffset = defaultValue(this.pixelOffset, source.pixelOffset);
this.eyeOffset = defaultValue(this.eyeOffset, source.eyeOffset);
this.horizontalOrigin = defaultValue(this.horizontalOrigin, source.horizontalOrigin);
this.verticalOrigin = defaultValue(this.verticalOrigin, source.verticalOrigin);
this.heightReference = defaultValue(this.heightReference, source.heightReference);
this.fillColor = defaultValue(this.fillColor, source.fillColor);
this.outlineColor = defaultValue(this.outlineColor, source.outlineColor);
this.outlineWidth = defaultValue(this.outlineWidth, source.outlineWidth);
this.translucencyByDistance = defaultValue(this.translucencyByDistance, source.translucencyByDistance);
this.pixelOffsetScaleByDistance = defaultValue(this.pixelOffsetScaleByDistance, source.pixelOffsetScaleByDistance);
this.scaleByDistance = defaultValue(this.scaleByDistance, source.scaleByDistance);
this.distanceDisplayCondition = defaultValue(this.distanceDisplayCondition, source.distanceDisplayCondition);
this.disableDepthTestDistance = defaultValue(this.disableDepthTestDistance, source.disableDepthTestDistance);
};
export default LabelGraphics;