/*global define*/define([ '../Core/defaultValue', '../Core/defined', '../Core/defineProperties', '../Core/DeveloperError', '../Core/Event', './createPropertyDescriptor' ], function( defaultValue, defined, defineProperties, DeveloperError, Event, createPropertyDescriptor) { 'use strict'; /** * Describes a two dimensional icon located at the position of the containing {@link Entity}. * <p> * <div align='center'> * <img src='images/Billboard.png' width='400' height='300' /><br /> * Example billboards * </div> * </p> * * @alias BillboardGraphics * @constructor * * @param {Object} [options] Object with the following properties: * @param {Property} [options.image] A Property specifying the Image, URI, or Canvas to use for the billboard. * @param {Property} [options.show=true] A boolean Property specifying the visibility of the billboard. * @param {Property} [options.scale=1.0] A numeric Property specifying the scale to apply to the image size. * @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.eyeOffset=Cartesian3.ZERO] A {@link Cartesian3} Property specifying the eye offset. * @param {Property} [options.pixelOffset=Cartesian2.ZERO] A {@link Cartesian2} Property specifying the pixel offset. * @param {Property} [options.rotation=0] A numeric Property specifying the rotation about the alignedAxis. * @param {Property} [options.alignedAxis=Cartesian3.ZERO] A {@link Cartesian3} Property specifying the unit vector axis of rotation. * @param {Property} [options.width] A numeric Property specifying the width of the billboard in pixels, overriding the native size. * @param {Property} [options.height] A numeric Property specifying the height of the billboard in pixels, overriding the native size. * @param {Property} [options.color=Color.WHITE] A Property specifying the tint {@link Color} of the image. * @param {Property} [options.scaleByDistance] A {@link NearFarScalar} Property used to scale the point based on distance from the camera. * @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.imageSubRegion] A Property specifying a {@link BoundingRectangle} that defines a sub-region of the image to use for the billboard, rather than the entire image, measured in pixels from the bottom-left. * @param {Property} [options.sizeInMeters] A boolean Property specifying whether this billboard's size should be measured in meters. * @param {Property} [options.heightReference=HeightReference.NONE] A Property specifying what the height is relative to. * @param {Property} [options.distanceDisplayCondition] A Property specifying at what distance from the camera that this billboard will be displayed. * * @demo {@link http://cesiumjs.org/Cesium/Apps/Sandcastle/index.html?src=Billboards.html|Cesium Sandcastle Billboard Demo} */ function BillboardGraphics(options) { this._image = undefined; this._imageSubscription = undefined; this._imageSubRegion = undefined; this._imageSubRegionSubscription = undefined; this._width = undefined; this._widthSubscription = undefined; this._height = undefined; this._heightSubscription = undefined; this._scale = undefined; this._scaleSubscription = undefined; this._rotation = undefined; this._rotationSubscription = undefined; this._alignedAxis = undefined; this._alignedAxisSubscription = undefined; this._horizontalOrigin = undefined; this._horizontalOriginSubscription = undefined; this._verticalOrigin = undefined; this._verticalOriginSubscription = undefined; this._color = undefined; this._colorSubscription = undefined; this._eyeOffset = undefined; this._eyeOffsetSubscription = undefined; this._heightReference = undefined; this._heightReferenceSubscription = undefined; this._pixelOffset = undefined; this._pixelOffsetSubscription = undefined; this._show = undefined; this._showSubscription = undefined; this._scaleByDistance = undefined; this._scaleByDistanceSubscription = undefined; this._translucencyByDistance = undefined; this._translucencyByDistanceSubscription = undefined; this._pixelOffsetScaleByDistance = undefined; this._pixelOffsetScaleByDistanceSubscription = undefined; this._sizeInMeters = undefined; this._sizeInMetersSubscription = undefined; this._distanceDisplayCondition = undefined; this._distanceDisplayConditionSubscription = undefined; this._definitionChanged = new Event(); this.merge(defaultValue(options, defaultValue.EMPTY_OBJECT)); } defineProperties(BillboardGraphics.prototype, { /** * Gets the event that is raised whenever a property or sub-property is changed or modified. * @memberof BillboardGraphics.prototype * * @type {Event} * @readonly */ definitionChanged : { get : function() { return this._definitionChanged; } }, /** * Gets or sets the Property specifying the Image, URI, or Canvas to use for the billboard. * @memberof BillboardGraphics.prototype * @type {Property} */ image : createPropertyDescriptor('image'), /** * Gets or sets the Property specifying a {@link BoundingRectangle} that defines a * sub-region of the <code>image</code> to use for the billboard, rather than the entire image, * measured in pixels from the bottom-left. * @memberof BillboardGraphics.prototype * @type {Property} */ imageSubRegion : createPropertyDescriptor('imageSubRegion'), /** * Gets or sets the numeric Property specifying the uniform scale to apply to the image. * A scale greater than <code>1.0</code> enlarges the billboard while a scale less than <code>1.0</code> shrinks it. * <p> * <div align='center'> * <img src='images/Billboard.setScale.png' width='400' height='300' /><br/> * From left to right in the above image, the scales are <code>0.5</code>, <code>1.0</code>, and <code>2.0</code>. * </div> * </p> * @memberof BillboardGraphics.prototype * @type {Property} * @default 1.0 */ scale : createPropertyDescriptor('scale'), /** * Gets or sets the numeric Property specifying the rotation of the image * counter clockwise from the <code>alignedAxis</code>. * @memberof BillboardGraphics.prototype * @type {Property} * @default 0 */ rotation : createPropertyDescriptor('rotation'), /** * Gets or sets the {@link Cartesian3} Property specifying the unit vector axis of rotation * in the fixed frame. When set to Cartesian3.ZERO the rotation is from the top of the screen. * @memberof BillboardGraphics.prototype * @type {Property} * @default Cartesian3.ZERO */ alignedAxis : createPropertyDescriptor('alignedAxis'), /** * Gets or sets the Property specifying the {@link HorizontalOrigin}. * @memberof BillboardGraphics.prototype * @type {Property} * @default HorizontalOrigin.CENTER */ horizontalOrigin : createPropertyDescriptor('horizontalOrigin'), /** * Gets or sets the Property specifying the {@link VerticalOrigin}. * @memberof BillboardGraphics.prototype * @type {Property} * @default VerticalOrigin.CENTER */ verticalOrigin : createPropertyDescriptor('verticalOrigin'), /** * Gets or sets the Property specifying the {@link Color} that is multiplied with the <code>image</code>. * This has two common use cases. First, the same white texture may be used by many different billboards, * each with a different color, to create colored billboards. Second, the color's alpha component can be * used to make the billboard translucent as shown below. An alpha of <code>0.0</code> makes the billboard * transparent, and <code>1.0</code> makes the billboard opaque. * <p> * <div align='center'> * <table border='0' cellpadding='5'><tr> * <td align='center'><code>default</code><br/><img src='images/Billboard.setColor.Alpha255.png' width='250' height='188' /></td> * <td align='center'><code>alpha : 0.5</code><br/><img src='images/Billboard.setColor.Alpha127.png' width='250' height='188' /></td> * </tr></table> * </div> * </p> * @memberof BillboardGraphics.prototype * @type {Property} * @default Color.WHITE */ color : createPropertyDescriptor('color'), /** * Gets or sets the {@link Cartesian3} Property specifying the billboard's offset in eye coordinates. * Eye coordinates is a left-handed coordinate system, where <code>x</code> points towards the viewer's * right, <code>y</code> points up, and <code>z</code> points into the screen. * <p> * An eye offset is commonly used to arrange multiple billboards or objects at the same position, e.g., to * arrange a billboard above its corresponding 3D model. * </p> * Below, the billboard 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. * <p> * <div align='center'> * <table border='0' cellpadding='5'><tr> * <td align='center'><img src='images/Billboard.setEyeOffset.one.png' width='250' height='188' /></td> * <td align='center'><img src='images/Billboard.setEyeOffset.two.png' width='250' height='188' /></td> * </tr></table> * <code>b.eyeOffset = new Cartesian3(0.0, 8000000.0, 0.0);</code> * </div> * </p> * @memberof BillboardGraphics.prototype * @type {Property} * @default Cartesian3.ZERO */ eyeOffset : createPropertyDescriptor('eyeOffset'), /** * Gets or sets the Property specifying the {@link HeightReference}. * @memberof BillboardGraphics.prototype * @type {Property} * @default HeightReference.NONE */ heightReference : createPropertyDescriptor('heightReference'), /** * Gets or sets the {@link Cartesian2} Property specifying the billboard's pixel offset in screen space * from the origin of this billboard. This is commonly used to align multiple billboards and labels at * the same position, e.g., an image and text. The screen space origin is the top, left corner of the * canvas; <code>x</code> increases from left to right, and <code>y</code> increases from top to bottom. * <p> * <div align='center'> * <table border='0' cellpadding='5'><tr> * <td align='center'><code>default</code><br/><img src='images/Billboard.setPixelOffset.default.png' width='250' height='188' /></td> * <td align='center'><code>b.pixeloffset = new Cartesian2(50, 25);</code><br/><img src='images/Billboard.setPixelOffset.x50y-25.png' width='250' height='188' /></td> * </tr></table> * The billboard's origin is indicated by the yellow point. * </div> * </p> * @memberof BillboardGraphics.prototype * @type {Property} * @default Cartesian2.ZERO */ pixelOffset : createPropertyDescriptor('pixelOffset'), /** * Gets or sets the boolean Property specifying the visibility of the billboard. * @memberof BillboardGraphics.prototype * @type {Property} * @default true */ show : createPropertyDescriptor('show'), /** * Gets or sets the numeric Property specifying the billboard's width in pixels. * When undefined, the native width is used. * @memberof BillboardGraphics.prototype * @type {Property} */ width : createPropertyDescriptor('width'), /** * Gets or sets the numeric Property specifying the height of the billboard in pixels. * When undefined, the native height is used. * @memberof BillboardGraphics.prototype * @type {Property} */ height : createPropertyDescriptor('height'), /** * Gets or sets {@link NearFarScalar} Property specifying the scale of the billboard based on the distance from the camera. * A billboard'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 billboard's scale remains clamped to the nearest bound. * @memberof BillboardGraphics.prototype * @type {Property} */ scaleByDistance : createPropertyDescriptor('scaleByDistance'), /** * Gets or sets {@link NearFarScalar} Property specifying the translucency of the billboard based on the distance from the camera. * A billboard'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 billboard's translucency remains clamped to the nearest bound. * @memberof BillboardGraphics.prototype * @type {Property} */ translucencyByDistance : createPropertyDescriptor('translucencyByDistance'), /** * Gets or sets {@link NearFarScalar} Property specifying the pixel offset of the billboard based on the distance from the camera. * A billboard'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 billboard's pixel offset remains clamped to the nearest bound. * @memberof BillboardGraphics.prototype * @type {Property} */ pixelOffsetScaleByDistance : createPropertyDescriptor('pixelOffsetScaleByDistance'), /** * Gets or sets the boolean Property specifying if this billboard's size will be measured in meters. * @memberof BillboardGraphics.prototype * @type {Property} * @default false */ sizeInMeters : createPropertyDescriptor('sizeInMeters'), /** * Gets or sets the {@link DistanceDisplayCondition} Property specifying at what distance from the camera that this billboard will be displayed. * @memberof BillboardGraphics.prototype * @type {Property} */ distanceDisplayCondition : createPropertyDescriptor('distanceDisplayCondition') }); /** * Duplicates this instance. * * @param {BillboardGraphics} [result] The object onto which to store the result. * @returns {BillboardGraphics} The modified result parameter or a new instance if one was not provided. */ BillboardGraphics.prototype.clone = function(result) { if (!defined(result)) { return new BillboardGraphics(this); } result.color = this._color; result.eyeOffset = this._eyeOffset; result.heightReference = this._heightReference; result.horizontalOrigin = this._horizontalOrigin; result.image = this._image; result.imageSubRegion = this._imageSubRegion; result.pixelOffset = this._pixelOffset; result.scale = this._scale; result.rotation = this._rotation; result.alignedAxis = this._alignedAxis; result.show = this._show; result.verticalOrigin = this._verticalOrigin; result.width = this._width; result.height = this._height; result.scaleByDistance = this._scaleByDistance; result.translucencyByDistance = this._translucencyByDistance; result.pixelOffsetScaleByDistance = this._pixelOffsetScaleByDistance; result.sizeInMeters = this._sizeInMeters; result.distanceDisplayCondition = this._distanceDisplayCondition; return result; }; /** * Assigns each unassigned property on this object to the value * of the same property on the provided source object. * * @param {BillboardGraphics} source The object to be merged into this object. */ BillboardGraphics.prototype.merge = function(source) { //>>includeStart('debug', pragmas.debug); if (!defined(source)) { throw new DeveloperError('source is required.'); } //>>includeEnd('debug'); this.color = defaultValue(this._color, source.color); this.eyeOffset = defaultValue(this._eyeOffset, source.eyeOffset); this.heightReference = defaultValue(this._heightReference, source.heightReference); this.horizontalOrigin = defaultValue(this._horizontalOrigin, source.horizontalOrigin); this.image = defaultValue(this._image, source.image); this.imageSubRegion = defaultValue(this._imageSubRegion, source.imageSubRegion); this.pixelOffset = defaultValue(this._pixelOffset, source.pixelOffset); this.scale = defaultValue(this._scale, source.scale); this.rotation = defaultValue(this._rotation, source.rotation); this.alignedAxis = defaultValue(this._alignedAxis, source.alignedAxis); this.show = defaultValue(this._show, source.show); this.verticalOrigin = defaultValue(this._verticalOrigin, source.verticalOrigin); this.width = defaultValue(this._width, source.width); this.height = defaultValue(this._height, source.height); this.scaleByDistance = defaultValue(this._scaleByDistance, source.scaleByDistance); this.translucencyByDistance = defaultValue(this._translucencyByDistance, source.translucencyByDistance); this.pixelOffsetScaleByDistance = defaultValue(this._pixelOffsetScaleByDistance, source.pixelOffsetScaleByDistance); this.sizeInMeters = defaultValue(this._sizeInMeters, source.sizeInMeters); this.distanceDisplayCondition = defaultValue(this._distanceDisplayCondition, source.distanceDisplayCondition); }; return BillboardGraphics;});