/*global define*/
define([
'../Core/Cartesian2',
'../Core/Cartesian3',
'../Core/Color',
'../Core/defaultValue',
'../Core/defined',
'../Core/defineProperties',
'../Core/DeveloperError',
'../Core/NearFarScalar',
'./Billboard',
'./HorizontalOrigin',
'./LabelStyle',
'./VerticalOrigin'
], function(
Cartesian2,
Cartesian3,
Color,
defaultValue,
defined,
defineProperties,
DeveloperError,
NearFarScalar,
Billboard,
HorizontalOrigin,
LabelStyle,
VerticalOrigin) {
"use strict";
function rebindAllGlyphs(label) {
if (!label._rebindAllGlyphs && !label._repositionAllGlyphs) {
// only push label if it's not already been marked dirty
label._labelCollection._labelsToUpdate.push(label);
}
label._rebindAllGlyphs = true;
}
function repositionAllGlyphs(label) {
if (!label._rebindAllGlyphs && !label._repositionAllGlyphs) {
// only push label if it's not already been marked dirty
label._labelCollection._labelsToUpdate.push(label);
}
label._repositionAllGlyphs = true;
}
/**
* A Label draws viewport-aligned text positioned in the 3D scene. This constructor
* should not be used directly, instead create labels by calling {@link LabelCollection#add}.
*
* @alias Label
* @internalConstructor
*
* @exception {DeveloperError} translucencyByDistance.far must be greater than translucencyByDistance.near
* @exception {DeveloperError} pixelOffsetScaleByDistance.far must be greater than pixelOffsetScaleByDistance.near
*
* @see LabelCollection
* @see LabelCollection#add
*
* @demo {@link http://cesiumjs.org/Cesium/Apps/Sandcastle/index.html?src=Labels.html|Cesium Sandcastle Labels Demo}
*/
var Label = function(options, labelCollection) {
options = defaultValue(options, defaultValue.EMPTY_OBJECT);
//>>includeStart('debug', pragmas.debug);
if (defined(options.translucencyByDistance) && options.translucencyByDistance.far <= options.translucencyByDistance.near) {
throw new DeveloperError('translucencyByDistance.far must be greater than translucencyByDistance.near.');
}
if (defined(options.pixelOffsetScaleByDistance) && options.pixelOffsetScaleByDistance.far <= options.pixelOffsetScaleByDistance.near) {
throw new DeveloperError('pixelOffsetScaleByDistance.far must be greater than pixelOffsetScaleByDistance.near.');
}
//>>includeEnd('debug');
this._text = defaultValue(options.text, '');
this._show = defaultValue(options.show, true);
this._font = defaultValue(options.font, '30px sans-serif');
this._fillColor = Color.clone(defaultValue(options.fillColor, Color.WHITE));
this._outlineColor = Color.clone(defaultValue(options.outlineColor, Color.BLACK));
this._outlineWidth = defaultValue(options.outlineWidth, 1.0);
this._style = defaultValue(options.style, LabelStyle.FILL);
this._verticalOrigin = defaultValue(options.verticalOrigin, VerticalOrigin.BOTTOM);
this._horizontalOrigin = defaultValue(options.horizontalOrigin, HorizontalOrigin.LEFT);
this._pixelOffset = Cartesian2.clone(defaultValue(options.pixelOffset, Cartesian2.ZERO));
this._eyeOffset = Cartesian3.clone(defaultValue(options.eyeOffset, Cartesian3.ZERO));
this._position = Cartesian3.clone(defaultValue(options.position, Cartesian3.ZERO));
this._scale = defaultValue(options.scale, 1.0);
this._id = options.id;
this._translucencyByDistance = options.translucencyByDistance;
this._pixelOffsetScaleByDistance = options.pixelOffsetScaleByDistance;
this._labelCollection = labelCollection;
this._glyphs = [];
this._rebindAllGlyphs = true;
this._repositionAllGlyphs = true;
};
defineProperties(Label.prototype, {
/**
* Determines if this label will be shown. Use this to hide or show a label, instead
* of removing it and re-adding it to the collection.
* @memberof Label.prototype
* @type {Boolean}
*/
show : {
get : function() {
return this._show;
},
set : function(value) {
//>>includeStart('debug', pragmas.debug);
if (!defined(value)) {
throw new DeveloperError('value is required.');
}
//>>includeEnd('debug');
if (this._show !== value) {
this._show = value;
var glyphs = this._glyphs;
for (var i = 0, len = glyphs.length; i < len; i++) {
var glyph = glyphs[i];
if (defined(glyph.billboard)) {
glyph.billboard.show = value;
}
}
}
}
},
/**
* Gets or sets the Cartesian position of this label.
* @memberof Label.prototype
* @type {Cartesian3}
*/
position : {
get : function() {
return this._position;
},
set : function(value) {
//>>includeStart('debug', pragmas.debug);
if (!defined(value)) {
throw new DeveloperError('value is required.');
}
//>>includeEnd('debug');
var position = this._position;
if (!Cartesian3.equals(position, value)) {
Cartesian3.clone(value, position);
var glyphs = this._glyphs;
for (var i = 0, len = glyphs.length; i < len; i++) {
var glyph = glyphs[i];
if (defined(glyph.billboard)) {
glyph.billboard.position = value;
}
}
}
}
},
/**
* Gets or sets the text of this label.
* @memberof Label.prototype
* @type {String}
*/
text : {
get : function() {
return this._text;
},
set : function(value) {
//>>includeStart('debug', pragmas.debug);
if (!defined(value)) {
throw new DeveloperError('value is required.');
}
//>>includeEnd('debug');
if (this._text !== value) {
this._text = value;
rebindAllGlyphs(this);
}
}
},
/**
* Gets or sets the font used to draw this label. Fonts are specified using the same syntax as the CSS 'font' property.
* @memberof Label.prototype
* @type {String}
* @see {@link http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#text-styles|HTML canvas 2D context text styles}
*/
font : {
get : function() {
return this._font;
},
set : function(value) {
//>>includeStart('debug', pragmas.debug);
if (!defined(value)) {
throw new DeveloperError('value is required.');
}
//>>includeEnd('debug');
if (this._font !== value) {
this._font = value;
rebindAllGlyphs(this);
}
}
},
/**
* Gets or sets the fill color of this label.
* @memberof Label.prototype
* @type {Color}
* @see {@link http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#fill-and-stroke-styles|HTML canvas 2D context fill and stroke styles}
*/
fillColor : {
get : function() {
return this._fillColor;
},
set : function(value) {
//>>includeStart('debug', pragmas.debug);
if (!defined(value)) {
throw new DeveloperError('value is required.');
}
//>>includeEnd('debug');
var fillColor = this._fillColor;
if (!Color.equals(fillColor, value)) {
Color.clone(value, fillColor);
rebindAllGlyphs(this);
}
}
},
/**
* Gets or sets the outline color of this label.
* @memberof Label.prototype
* @type {Color}
* @see {@link http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#fill-and-stroke-styles|HTML canvas 2D context fill and stroke styles}
*/
outlineColor : {
get : function() {
return this._outlineColor;
},
set : function(value) {
//>>includeStart('debug', pragmas.debug);
if (!defined(value)) {
throw new DeveloperError('value is required.');
}
//>>includeEnd('debug');
var outlineColor = this._outlineColor;
if (!Color.equals(outlineColor, value)) {
Color.clone(value, outlineColor);
rebindAllGlyphs(this);
}
}
},
/**
* Gets or sets the outline width of this label.
* @memberof Label.prototype
* @type {Number}
* @see {@link http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html#fill-and-stroke-styles|HTML canvas 2D context fill and stroke styles}
*/
outlineWidth : {
get : function() {
return this._outlineWidth;
},
set : function(value) {
//>>includeStart('debug', pragmas.debug);
if (!defined(value)) {
throw new DeveloperError('value is required.');
}
//>>includeEnd('debug');
if (this._outlineWidth !== value) {
this._outlineWidth = value;
rebindAllGlyphs(this);
}
}
},
/**
* Gets or sets the style of this label.
* @memberof Label.prototype
* @type {LabelStyle}
*/
style : {
get : function() {
return this._style;
},
set : function(value) {
//>>includeStart('debug', pragmas.debug);
if (!defined(value)) {
throw new DeveloperError('value is required.');
}
//>>includeEnd('debug');
if (this._style !== value) {
this._style = value;
rebindAllGlyphs(this);
}
}
},
/**
* Gets or sets the pixel offset in screen space from the origin of this label. This is commonly used
* to align multiple labels and billboards 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 Label.prototype
* @type {Cartesian2}
*/
pixelOffset : {
get : function() {
return this._pixelOffset;
},
set : function(value) {
//>>includeStart('debug', pragmas.debug);
if (!defined(value)) {
throw new DeveloperError('value is required.');
}
//>>includeEnd('debug');
var pixelOffset = this._pixelOffset;
if (!Cartesian2.equals(pixelOffset, value)) {
Cartesian2.clone(value, pixelOffset);
var glyphs = this._glyphs;
for (var i = 0, len = glyphs.length; i < len; i++) {
var glyph = glyphs[i];
if (defined(glyph.billboard)) {
glyph.billboard.pixelOffset = value;
}
}
}
}
},
/**
* Gets or sets near and far translucency properties of a Label based on the Label's 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. If undefined,
* translucencyByDistance will be disabled.
* @memberof Label.prototype
* @type {NearFarScalar}
*
* @example
* // Example 1.
* // Set a label's translucencyByDistance to 1.0 when the
* // camera is 1500 meters from the label and disappear as
* // the camera distance approaches 8.0e6 meters.
* text.translucencyByDistance = new Cesium.NearFarScalar(1.5e2, 1.0, 8.0e6, 0.0);
*
* @example
* // Example 2.
* // disable translucency by distance
* text.translucencyByDistance = undefined;
*/
translucencyByDistance : {
get : function() {
return this._translucencyByDistance;
},
set : function(value) {
//>>includeStart('debug', pragmas.debug);
if (defined(value) && value.far <= value.near) {
throw new DeveloperError('far distance must be greater than near distance.');
}
//>>includeEnd('debug');
var translucencyByDistance = this._translucencyByDistance;
if (!NearFarScalar.equals(translucencyByDistance, value)) {
this._translucencyByDistance = NearFarScalar.clone(value, translucencyByDistance);
var glyphs = this._glyphs;
for (var i = 0, len = glyphs.length; i < len; i++) {
var glyph = glyphs[i];
if (defined(glyph.billboard)) {
glyph.billboard.translucencyByDistance = value;
}
}
}
}
},
/**
* Gets or sets near and far pixel offset scaling properties of a Label based on the Label's distance from the camera.
* A label's pixel offset will be scaled 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 scaling remains clamped to the nearest bound. If undefined,
* pixelOffsetScaleByDistance will be disabled.
* @memberof Label.prototype
* @type {NearFarScalar}
*
* @example
* // Example 1.
* // Set a label's pixel offset scale to 0.0 when the
* // camera is 1500 meters from the label and scale pixel offset to 10.0 pixels
* // in the y direction the camera distance approaches 8.0e6 meters.
* text.pixelOffset = new Cesium.Cartesian2(0.0, 1.0);
* text.pixelOffsetScaleByDistance = new Cesium.NearFarScalar(1.5e2, 0.0, 8.0e6, 10.0);
*
* @example
* // Example 2.
* // disable pixel offset by distance
* text.pixelOffsetScaleByDistance = undefined;
*/
pixelOffsetScaleByDistance : {
get : function() {
return this._pixelOffsetScaleByDistance;
},
set : function(value) {
//>>includeStart('debug', pragmas.debug);
if (defined(value) && value.far <= value.near) {
throw new DeveloperError('far distance must be greater than near distance.');
}
//>>includeEnd('debug');
var pixelOffsetScaleByDistance = this._pixelOffsetScaleByDistance;
if (!NearFarScalar.equals(pixelOffsetScaleByDistance, value)) {
this._pixelOffsetScaleByDistance = NearFarScalar.clone(value, pixelOffsetScaleByDistance);
var glyphs = this._glyphs;
for (var i = 0, len = glyphs.length; i < len; i++) {
var glyph = glyphs[i];
if (defined(glyph.billboard)) {
glyph.billboard.pixelOffsetScaleByDistance = value;
}
}
}
}
},
/**
* Gets and sets the 3D Cartesian offset applied to this label 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. Eye coordinates use the same scale as world and model coordinates,
* which is typically meters.
*
* An eye offset is commonly used to arrange multiple label 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 Label.prototype
* @type {Cartesian3}
*/
eyeOffset : {
get : function() {
return this._eyeOffset;
},
set : function(value) {
//>>includeStart('debug', pragmas.debug);
if (!defined(value)) {
throw new DeveloperError('value is required.');
}
//>>includeEnd('debug');
var eyeOffset = this._eyeOffset;
if (!Cartesian3.equals(eyeOffset, value)) {
Cartesian3.clone(value, eyeOffset);
var glyphs = this._glyphs;
for (var i = 0, len = glyphs.length; i < len; i++) {
var glyph = glyphs[i];
if (defined(glyph.billboard)) {
glyph.billboard.eyeOffset = value;
}
}
}
}
},
/**
* Gets or sets the horizontal origin of this label, which determines if the label is drawn
* to the left, center, or right of its position.
*
*
*

*
* @memberof Label.prototype
* @type {HorizontalOrigin}
* @example
* // Use a top, right origin
* l.horizontalOrigin = Cesium.HorizontalOrigin.RIGHT;
* l.verticalOrigin = Cesium.VerticalOrigin.TOP;
*/
horizontalOrigin : {
get : function() {
return this._horizontalOrigin;
},
set : function(value) {
//>>includeStart('debug', pragmas.debug);
if (!defined(value)) {
throw new DeveloperError('value is required.');
}
//>>includeEnd('debug');
if (this._horizontalOrigin !== value) {
this._horizontalOrigin = value;
repositionAllGlyphs(this);
}
}
},
/**
* Gets or sets the vertical origin of this label, which determines if the label is
* to the above, below, or at the center of its position.
*
*
*

*
* @memberof Label.prototype
* @type {VerticalOrigin}
* @example
* // Use a top, right origin
* l.horizontalOrigin = Cesium.HorizontalOrigin.RIGHT;
* l.verticalOrigin = Cesium.VerticalOrigin.TOP;
*/
verticalOrigin : {
get : function() {
return this._verticalOrigin;
},
set : function(value) {
//>>includeStart('debug', pragmas.debug);
if (!defined(value)) {
throw new DeveloperError('value is required.');
}
//>>includeEnd('debug');
if (this._verticalOrigin !== value) {
this._verticalOrigin = value;
var glyphs = this._glyphs;
for (var i = 0, len = glyphs.length; i < len; i++) {
var glyph = glyphs[i];
if (defined(glyph.billboard)) {
glyph.billboard.verticalOrigin = value;
}
}
repositionAllGlyphs(this);
}
}
},
/**
* Gets or sets the uniform scale that is multiplied with the label's size in pixels.
* A scale of 1.0
does not change the size of the label; a scale greater than
* 1.0
enlarges the label; a positive scale less than 1.0
shrinks
* the label.
*
* Applying a large scale value may pixelate the label. To make text larger without pixelation,
* use a larger font size when calling {@link Label#font} instead.
*
*
*

* From left to right in the above image, the scales are
0.5
,
1.0
,
* and
2.0
.
*
* @memberof Label.prototype
* @type {Number}
*/
scale : {
get : function() {
return this._scale;
},
set : function(value) {
//>>includeStart('debug', pragmas.debug);
if (!defined(value)) {
throw new DeveloperError('value is required.');
}
//>>includeEnd('debug');
if (this._scale !== value) {
this._scale = value;
var glyphs = this._glyphs;
for (var i = 0, len = glyphs.length; i < len; i++) {
var glyph = glyphs[i];
if (defined(glyph.billboard)) {
glyph.billboard.scale = value;
}
}
repositionAllGlyphs(this);
}
}
},
/**
* Gets or sets the user-defined object returned when the label is picked.
* @memberof Label.prototype
* @type {Object}
*/
id : {
get : function() {
return this._id;
},
set : function(value) {
if (this._id !== value) {
this._id = value;
var glyphs = this._glyphs;
for (var i = 0, len = glyphs.length; i < len; i++) {
var glyph = glyphs[i];
if (defined(glyph.billboard)) {
glyph.billboard.id = value;
}
}
}
}
}
});
/**
* Computes the screen-space position of the label's origin, taking into account eye and pixel offsets.
* 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.
*
* @param {Scene} scene The scene the label is in.
* @returns {Cartesian2} The screen-space position of the label.
*
* @see Label#eyeOffset
* @see Label#pixelOffset
*
* @example
* console.log(l.computeScreenSpacePosition(scene).toString());
*/
Label.prototype.computeScreenSpacePosition = function(scene) {
//>>includeStart('debug', pragmas.debug);
if (!defined(scene)) {
throw new DeveloperError('context is required.');
}
//>>includeEnd('debug');
var labelCollection = this._labelCollection;
var modelMatrix = labelCollection.modelMatrix;
var actualPosition = Billboard._computeActualPosition(this._position, scene.frameState, modelMatrix);
var windowCoordinates = Billboard._computeScreenSpacePosition(modelMatrix, actualPosition, this._eyeOffset, this._pixelOffset, scene);
windowCoordinates.y = scene.canvas.clientHeight - windowCoordinates.y;
return windowCoordinates;
};
/**
* Determines if this label equals another label. Labels are equal if all their properties
* are equal. Labels in different collections can be equal.
*
* @param {Label} other The label to compare for equality.
* @returns {Boolean} true
if the labels are equal; otherwise, false
.
*/
Label.prototype.equals = function(other) {
return this === other ||
defined(other) &&
this._show === other._show &&
this._scale === other._scale &&
this._style === other._style &&
this._verticalOrigin === other._verticalOrigin &&
this._horizontalOrigin === other._horizontalOrigin &&
this._text === other._text &&
this._font === other._font &&
Cartesian3.equals(this._position, other._position) &&
Color.equals(this._fillColor, other._fillColor) &&
Color.equals(this._outlineColor, other._outlineColor) &&
Cartesian2.equals(this._pixelOffset, other._pixelOffset) &&
Cartesian3.equals(this._eyeOffset, other._eyeOffset) &&
NearFarScalar.equals(this._translucencyByDistance, other._translucencyByDistance) &&
NearFarScalar.equals(this._pixelOffsetScaleByDistance, other._pixelOffsetScaleByDistance) &&
this._id === other._id;
};
/**
* Returns true if this object was destroyed; otherwise, false.
*
* If this object was destroyed, it should not be used; calling any function other than
* isDestroyed
will result in a {@link DeveloperError} exception.
*
* @returns {Boolean} True if this object was destroyed; otherwise, false.
*/
Label.prototype.isDestroyed = function() {
return false;
};
return Label;
});