diff --git a/interface/src/raypick/PickScriptingInterface.h b/interface/src/raypick/PickScriptingInterface.h
index e973ee3643..473413ca58 100644
--- a/interface/src/raypick/PickScriptingInterface.h
+++ b/interface/src/raypick/PickScriptingInterface.h
@@ -29,7 +29,7 @@
* @property {FilterFlags} PICK_AVATAR_ENTITIES - Include avatar entities when intersecting. Read-only.
* @property {FilterFlags} PICK_LOCAL_ENTITIES - Include local entities when intersecting. Read-only.
* @property {FilterFlags} PICK_AVATARS - Include avatars when intersecting. Read-only.
- * @property {FilterFlags} PICK_HUD - Include the HUD sphere when intersecting in HMD mode. Read-only.
+ * @property {FilterFlags} PICK_HUD - Include the HUD surface when intersecting in HMD mode. Read-only.
*
* @property {FilterFlags} PICK_ENTITIES - Include domain and avatar entities when intersecting. Read-only.
* Deprecated: This property is deprecated and will be removed. Use PICK_DOMAIN_ENTITIES |
@@ -61,7 +61,7 @@
* Deprecated: This property is deprecated and will be removed. Use
* INTERSECTED_LOCAL_ENTITY instead.
* @property {IntersectionType} INTERSECTED_AVATAR - Intersected an avatar. Read-only.
- * @property {IntersectionType} INTERSECTED_HUD - Intersected the HUD sphere. Read-only.
+ * @property {IntersectionType} INTERSECTED_HUD - Intersected the HUD surface. Read-only.
*
* @property {number} perFrameTimeBudget - The maximum time, in microseconds, to spend per frame updating pick results.
*/
diff --git a/interface/src/raypick/RayPickScriptingInterface.h b/interface/src/raypick/RayPickScriptingInterface.h
index 2a00847510..204407e92d 100644
--- a/interface/src/raypick/RayPickScriptingInterface.h
+++ b/interface/src/raypick/RayPickScriptingInterface.h
@@ -33,7 +33,7 @@
* Read-only.
* @property {FilterFlags} PICK_OVERLAYS - Include local entities when intersecting. Read-only.
* @property {FilterFlags} PICK_AVATARS - Include avatars when intersecting. Read-only.
- * @property {FilterFlags} PICK_HUD - Include the HUD sphere when intersecting in HMD mode. Read-only.
+ * @property {FilterFlags} PICK_HUD - Include the HUD surface when intersecting in HMD mode. Read-only.
* @property {FilterFlags} PICK_PRECISE - Pick against exact meshes. Read-only.
* @property {FilterFlags} PICK_INCLUDE_INVISIBLE - Include invisible objects when intersecting. Read-only.
* @property {FilterFlags} PICK_INCLUDE_NONCOLLIDABLE - Include non-collidable objects when intersecting. Read-only.
@@ -43,7 +43,7 @@
* @property {IntersectionType} INTERSECTED_LOCAL_ENTITY - Intersected a local entity. Read-only.
* @property {IntersectionType} INTERSECTED_OVERLAY - Intersected an entity (3D Overlays no longer exist). Read-only.
* @property {IntersectionType} INTERSECTED_AVATAR - Intersected an avatar. Read-only.
- * @property {IntersectionType} INTERSECTED_HUD - Intersected the HUD sphere. Read-only.
+ * @property {IntersectionType} INTERSECTED_HUD - Intersected the HUD surface. Read-only.
*/
class RayPickScriptingInterface : public QObject, public Dependency {
Q_OBJECT
diff --git a/interface/src/scripting/Audio.h b/interface/src/scripting/Audio.h
index d62fd70cc4..aab1ade95b 100644
--- a/interface/src/scripting/Audio.h
+++ b/interface/src/scripting/Audio.h
@@ -459,7 +459,7 @@ signals:
/**jsdoc
* Triggered when the server injector gain changes.
* @function Audio.serverInjectorGainChanged
- * @param {float} gain - The new server injector gain value.
+ * @param {number} gain - The new server injector gain value.
* @returns {Signal}
*/
void serverInjectorGainChanged(float gain);
diff --git a/interface/src/scripting/HMDScriptingInterface.h b/interface/src/scripting/HMDScriptingInterface.h
index 030f817477..30a1353d81 100644
--- a/interface/src/scripting/HMDScriptingInterface.h
+++ b/interface/src/scripting/HMDScriptingInterface.h
@@ -62,7 +62,7 @@ class QScriptEngine;
* @property {Uuid} miniTabletScreenID - The UUID of the mini tablet's screen entity. null if not in HMD mode.
* @property {number} miniTabletHand - The hand that the mini tablet is displayed on: 0 for left hand,
* 1 for right hand, -1 if not in HMD mode.
- * @property {bool} miniTabletEnabled=true - true if the mini tablet is enabled to be displayed, otherwise
+ * @property {boolean} miniTabletEnabled=true - true if the mini tablet is enabled to be displayed, otherwise
* false.
* @property {Rect} playArea=0,0,0,0 - The size and position of the HMD play area in sensor coordinates. Read-only.
* @property {Vec3[]} sensorPositions=[]] - The positions of the VR system sensors in sensor coordinates. Read-only.
diff --git a/interface/src/scripting/WindowScriptingInterface.h b/interface/src/scripting/WindowScriptingInterface.h
index eab1c65ebb..010f3bcca2 100644
--- a/interface/src/scripting/WindowScriptingInterface.h
+++ b/interface/src/scripting/WindowScriptingInterface.h
@@ -658,7 +658,8 @@ signals:
/**jsdoc
* Triggered when you try to visit a domain but are redirected into the error state.
* @function Window.redirectErrorStateChanged
- * @param {boolean} isInErrorState - If true, the user has been redirected to the error URL.
+ * @param {boolean} isInErrorState - true if the user has been redirected to the error URL, false
+ * if they haven't.
* @returns {Signal}
*/
void redirectErrorStateChanged(bool isInErrorState);
@@ -666,8 +667,8 @@ signals:
/**jsdoc
* Triggered when the interstitial mode changes.
* @function Window.interstitialModeChanged
- * @param {bool} interstitialMode - The new interstitial mode value. If true, the interstitial graphics are
- * displayed when the domain is loading.
+ * @param {boolean} interstitialMode - true if the interstitial graphics are displayed when the domain is
+ * loading, false if they are not.
* @returns {Signal}
*/
void interstitialModeChanged(bool interstitialMode);
diff --git a/interface/src/ui/overlays/Overlays.cpp b/interface/src/ui/overlays/Overlays.cpp
index 2ade5edda5..be371c900b 100644
--- a/interface/src/ui/overlays/Overlays.cpp
+++ b/interface/src/ui/overlays/Overlays.cpp
@@ -1333,127 +1333,170 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) {
* An overlay may be one of the following types:
*
*
- * | Value | 2D/3D | Description |
|---|
+ * | Value | 2D/3D | Description | Properties |
|---|
*
*
- * image | 2D | An image. Synonym: billboard. |
- * rectangle | 2D | A rectangle. |
- * text | 2D | Text. |
- * cube | 3D | A cube. Can also use a shape overlay to create a cube. |
- * sphere | 3D | A sphere. Can also use a shape overlay to create a sphere. |
- * rectangle3d | 3D | A rectangle. |
- * shape | 3D | A geometric shape, such as a cube, sphere, or cylinder. |
- * model | 3D | A model. |
- * text3d | 3D | Text. |
- * image3d | 3D | An image. |
- * web3d | 3D | Web content. |
- * line3d | 3D | A line. |
- * grid | 3D | A grid of lines in a plane. |
- * circle3d | 3D | A circle. |
+ * "rectangle" | 2D |
+ * A rectangle. |
+ * {@link Overlays.OverlayProperties-Rectangle|OverlayProperties-Rectangle} |
+ * "image" | 2D |
+ * An image. |
+ * {@link Overlays.OverlayProperties-Image|OverlayProperties-Image} |
+ * "text" | 2D |
+ * Some text. |
+ * {@link Overlays.OverlayProperties-Text|OverlayProperties-Text} |
+ * "cube" | 3D |
+ * A cube. A "shape" overlay can also be used to create a cube.
+ * Deprecated.
+ * |
+ * {@link Overlays.OverlayProperties-Cube|OverlayProperties-Cube} |
+ * "sphere" | 3D |
+ * A sphere. A "shape" overlay can also be used to create a sphere.
+ * Deprecated. |
+ * {@link Overlays.OverlayProperties-Sphere|OverlayProperties-Sphere} |
+ * "shape" | 3D |
+ * A geometric shape, such as a cube, sphere, or cylinder.
+ * Deprecated. |
+ * {@link Overlays.OverlayProperties-Shape|OverlayProperties-Shape} |
+ * "model" | 3D |
+ * A model.
+ * Deprecated. |
+ * {@link Overlays.OverlayProperties-Model|OverlayProperties-Model} |
+ * "image3d" | 3D |
+ * An image. Synonym: "billboard".
+ * Deprecated. |
+ * {@link Overlays.OverlayProperties-Image3D|OverlayProperties-Image3D} |
+ * "rectangle3d" | 3D |
+ * A rectangle.
+ * Deprecated. |
+ * {@link Overlays.OverlayProperties-Rectangle3D|OverlayProperties-Rectangle3D} |
+ * "text3d" | 3D |
+ * Some text.
+ * Deprecated. |
+ * {@link Overlays.OverlayProperties-Text3D|OverlayProperties-Text3D} |
+ * "web3d" | 3D |
+ * Web content.
+ * Deprecated. |
+ * {@link Overlays.OverlayProperties-Web3D|OverlayProperties-Web3D} |
+ * "line3d" | 3D |
+ * A line.
+ * Deprecated. |
+ * {@link Overlays.OverlayProperties-Line3D|OverlayProperties-Line3D} |
+ * "grid" | 3D |
+ * A grid of lines in a plane.
+ * Deprecated. |
+ * {@link Overlays.OverlayProperties-Grid|OverlayProperties-Grid} |
+ * "circle3d" | 3D |
+ * A circle.
+ * Deprecated. |
+ * {@link Overlays.OverlayProperties-Circle3D|OverlayProperties-Circle3D} |
*
*
* 2D overlays are rendered on the display surface in desktop mode and on the HUD surface in HMD mode. 3D overlays are
- * rendered at a position and orientation in-world, but are deprecated (use local entities instead).
- *
Each overlay type has different {@link Overlays.OverlayProperties|OverlayProperties}.
+ * rendered at a position and orientation in-world.
+ * 3D overlays are deprecated. Use local {@link Entities} instead.
* @typedef {string} Overlays.OverlayType
*/
/**jsdoc
- * Different overlay types have different properties: some common to all overlays (listed below) and some specific to each
- * {@link Overlays.OverlayType|OverlayType} (linked to below). The properties are accessed as an object of property names and
- * values. 3D Overlays are local entities, internally, so they also support the corresponding entity properties.
- *
+ * Different overlay types have different properties: some common to all overlays (listed in the table) and some specific to
+ * each {@link Overlays.OverlayType|OverlayType} (linked to below).
+ * 3D overlays are local entities, internally, so they also support the relevant entity's properties.
* @typedef {object} Overlays.OverlayProperties
* @property {Uuid} id - The ID of the overlay. Read-only.
- * @property {Overlays.OverlayType} type - The overlay type. Read-only.
- * @property {boolean} visible=true - If true, the overlay is rendered, otherwise it is not rendered.
+ * @property {Overlays.OverlayType} type - The overlay's type. Read-only.
+ * @property {boolean} visible=true - true if the overlay is rendered, false if it isn't.
*
- * @see The different entity types have additional properties as follows:
+ * @see {@link Overlays.OverlayProperties-Rectangle|OverlayProperties-Rectangle}
* @see {@link Overlays.OverlayProperties-Image|OverlayProperties-Image}
* @see {@link Overlays.OverlayProperties-Text|OverlayProperties-Text}
- * @see {@link Overlays.OverlayProperties-Rectangle|OverlayProperties-Rectangle}
- * @see {@link Overlays.OverlayProperties-Cube|OverlayProperties-Cube}
- * @see {@link Overlays.OverlayProperties-Sphere|OverlayProperties-Sphere}
- * @see {@link Overlays.OverlayProperties-Rectangle3D|OverlayProperties-Rectangle3D}
- * @see {@link Overlays.OverlayProperties-Shape|OverlayProperties-Shape}
- * @see {@link Overlays.OverlayProperties-Model|OverlayProperties-Model}
- * @see {@link Overlays.OverlayProperties-Text3D|OverlayProperties-Text3D}
- * @see {@link Overlays.OverlayProperties-Image3D|OverlayProperties-Image3D}
- * @see {@link Overlays.OverlayProperties-Web|OverlayProperties-Web}
- * @see {@link Overlays.OverlayProperties-Line|OverlayProperties-Line}
- * @see {@link Overlays.OverlayProperties-Grid|OverlayProperties-Grid}
- * @see {@link Overlays.OverlayProperties-Circle|OverlayProperties-Circle}
+ * @see {@link Overlays.OverlayProperties-Cube|OverlayProperties-Cube} Deprecated.
+ * @see {@link Overlays.OverlayProperties-Sphere|OverlayProperties-Sphere} Deprecated.
+ * @see {@link Overlays.OverlayProperties-Shape|OverlayProperties-Shape} Deprecated.
+ * @see {@link Overlays.OverlayProperties-Model|OverlayProperties-Model} Deprecated.
+ * @see {@link Overlays.OverlayProperties-Rectangle3D|OverlayProperties-Rectangle3D} Deprecated.
+ * @see {@link Overlays.OverlayProperties-Image3D|OverlayProperties-Image3D} Deprecated.
+ * @see {@link Overlays.OverlayProperties-Text3D|OverlayProperties-Text3D} Deprecated.
+ * @see {@link Overlays.OverlayProperties-Web3D|OverlayProperties-Web3D} Deprecated.
+ * @see {@link Overlays.OverlayProperties-Line3D|OverlayProperties-Line3D} Deprecated.
+ * @see {@link Overlays.OverlayProperties-Grid|OverlayProperties-Grid} Deprecated.
+ * @see {@link Overlays.OverlayProperties-Circle3D|OverlayProperties-Circle3D} Deprecated.
*/
/**jsdoc
- * The "Image" {@link Overlays.OverlayType|OverlayType} is a 2D image.
+ * The "image" {@link Overlays.OverlayType|OverlayType} is for 2D images.
+ * It has properties in addition to the common {@link Overlays.OverlayProperties|OverlayProperties}.
* @typedef {object} Overlays.OverlayProperties-Image
* @property {Rect} bounds - The position and size of the image display area, in pixels. Write-only.
* @property {number} x - Integer left, x-coordinate value of the image display area = bounds.x.
* Write-only.
- * @property {number} y - Integer top, y-coordinate value of the image display area = bounds.y.
+ * @property {number} y - Integer top, y-coordinate value of the image display area = bounds.y.
* Write-only.
* @property {number} width - Integer width of the image display area = bounds.width. Write-only.
- * @property {number} height - Integer height of the image display area = bounds.height. Write-only.
+ * @property {number} height - Integer height of the image display area = bounds.height. Write-only.
* @property {string} imageURL - The URL of the image file to display. The image is scaled to fit to the bounds.
* Write-only.
- * @property {Vec2} subImage=0,0 - Integer coordinates of the top left pixel to start using image content from.
+ * @property {Rect} subImage - The portion of the image to use. If not specified, the whole image is used.
* Write-only.
* @property {Color} color=0,0,0 - The color to apply over the top of the image to colorize it. Write-only.
- * @property {number} alpha=0.0 - The opacity of the color applied over the top of the image, 0.0 -
+ * @property {number} alpha=0.0 - The opacity of the color applied over the top of the image, 0.0 –
* 1.0. Write-only.
*/
/**jsdoc
- * The "Text" {@link Overlays.OverlayType|OverlayType} is for 2D text.
+ * The "text" {@link Overlays.OverlayType|OverlayType} is for 2D text.
+ * It has properties in addition to the common {@link Overlays.OverlayProperties|OverlayProperties}.
* @typedef {object} Overlays.OverlayProperties-Text
* @property {Rect} bounds - The position and size of the rectangle, in pixels. Write-only.
* @property {number} x - Integer left, x-coordinate value = bounds.x. Write-only.
* @property {number} y - Integer top, y-coordinate value = bounds.y. Write-only.
* @property {number} width - Integer width of the rectangle = bounds.width. Write-only.
* @property {number} height - Integer height of the rectangle = bounds.height. Write-only.
- *
- * @property {number} margin=0 - Sets the leftMargin and topMargin values, in pixels.
+ * @property {number} margin=0 - The leftMargin and topMargin values, in pixels.
* Write-only.
* @property {number} leftMargin=0 - The left margin's size, in pixels. This value is also used for the right margin.
* Write-only.
* @property {number} topMargin=0 - The top margin's size, in pixels. This value is also used for the bottom margin.
* Write-only.
- * @property {string} text="" - The text to display. Text does not automatically wrap; use \n for a line break. Text
- * is clipped to the bounds. Write-only.
+ * @property {string} text="" - The text to display. Text does not automatically wrap; use "\n" for a line break.
+ * Text is clipped to the bounds. Write-only.
* @property {number} font.size=18 - The size of the text, in pixels. Write-only.
* @property {number} lineHeight=18 - The height of a line of text, in pixels. Write-only.
* @property {Color} color=255,255,255 - The color of the text. Synonym: textColor. Write-only.
- * @property {number} alpha=1.0 - The opacity of the overlay, 0.0 - 1.0. Write-only.
+ * @property {number} alpha=1.0 - The opacity of the overlay, 0.0 – 1.0. Write-only.
* @property {Color} backgroundColor=0,0,0 - The color of the background rectangle. Write-only.
- * @property {number} backgroundAlpha=0.7 - The opacity of the background rectangle. Write-only.
+ * @property {number} backgroundAlpha=0.7 - The opacity of the background rectangle, 0.0 – 1.0.
+ * Write-only.
*/
/**jsdoc
- * The "Rectangle" {@link Overlays.OverlayType|OverlayType} is for 2D rectangles.
+ * The "rectangle" {@link Overlays.OverlayType|OverlayType} is for 2D rectangles.
+ * It has properties in addition to the common {@link Overlays.OverlayProperties|OverlayProperties}.
* @typedef {object} Overlays.OverlayProperties-Rectangle
* @property {Rect} bounds - The position and size of the rectangle, in pixels. Write-only.
* @property {number} x - Integer left, x-coordinate value = bounds.x. Write-only.
* @property {number} y - Integer top, y-coordinate value = bounds.y. Write-only.
* @property {number} width - Integer width of the rectangle = bounds.width. Write-only.
* @property {number} height - Integer height of the rectangle = bounds.height. Write-only.
- *
+ * @property {number} radius=0 - Integer corner radius, in pixels. Write-only.
* @property {Color} color=0,0,0 - The color of the overlay. Write-only.
- * @property {number} alpha=1.0 - The opacity of the overlay, 0.0 - 1.0. Write-only.
+ * @property {number} alpha=1.0 - The opacity of the overlay, 0.0 – 1.0. Write-only.
* @property {number} borderWidth=1 - Integer width of the border, in pixels. The border is drawn within the rectangle's bounds.
* It is not drawn unless either borderColor or borderAlpha are specified. Write-only.
- * @property {number} radius=0 - Integer corner radius, in pixels. Write-only.
* @property {Color} borderColor=0,0,0 - The color of the border. Write-only.
- * @property {number} borderAlpha=1.0 - The opacity of the border, 0.0 - 1.0.
+ * @property {number} borderAlpha=1.0 - The opacity of the border, 0.0 – 1.0.
* Write-only.
*/
/**jsdoc
- * The "Cube" {@link Overlays.OverlayType|OverlayType} is for 3D cubes.
+ * The "cube" {@link Overlays.OverlayType|OverlayType} is for 3D cubes.
+ * It has properties in addition to the common {@link Overlays.OverlayProperties|OverlayProperties}.
+ * It additionally has properties per the {@link Entities.EntityProperties-Box|Box} entity.
+ * Deprecated: Use local {@link Entities} instead.
* @typedef {object} Overlays.OverlayProperties-Cube
* @property {string} name - The name of the overlay.
* @property {Color} color=255,255,255 - The color of the overlay.
- * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0.
+ * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 – 1.0.
* @property {number} pulseMax=0 - The maximum value of the pulse multiplier.
* @property {number} pulseMin=0 - The minimum value of the pulse multiplier.
* @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from
@@ -1475,24 +1518,33 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) {
* parentID set, otherwise the same value as position.
* @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a
* parentID set, otherwise the same value as rotation. Synonym: localOrientation.
- * @property {boolean} isSolid=false - Synonyms: solid, isFilled, and filled.
+ * @property {boolean} isSolid=false - true if the overlay is rendered as a solid, false if it is
+ * rendered as a wire frame.
+ * Synonyms: solid, isFilled, and filled.
* Antonyms: isWire and wire.
- * @property {boolean} ignorePickIntersection=false - If true, picks ignore the overlay. ignoreRayIntersection is a synonym.
- * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of objects in the world, but behind the HUD.
- * @property {boolean} drawHUDLayer=false - If true, the overlay is rendered in front of everything, including the HUD.
- * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed.
+ * @property {boolean} ignorePickIntersection=false - true if {@link Picks} ignore the overlay, false
+ * if they don't.
+ * Synonym: ignoreRayIntersection.
+ * @property {boolean} drawInFront=false - true if the overlay is rendered on top of the world layer but behind
+ * the HUD surface.
+ * @property {boolean} drawHUDLayer=false - true if the overlay is rendered in front of everything, including the
+ * HUD surface.
+ * @property {boolean} grabbable=false - true if the overlay can be grabbed, false if it can't be.
* @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to.
- * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if
- * parentID is an avatar skeleton. A value of 65535 means "no joint".
- *
+ * @property {number} parentJointIndex=65535 - Integer value specifying the joint of the entity or avatar that the entity is
+ * parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather
+ * than a joint.
*/
/**jsdoc
- * The "Sphere" {@link Overlays.OverlayType|OverlayType} is for 3D spheres.
+ * The "sphere" {@link Overlays.OverlayType|OverlayType} is for 3D spheres.
+ * It has properties in addition to the common {@link Overlays.OverlayProperties|OverlayProperties}.
+ * It additionally has properties per the {@link Entities.EntityProperties-Sphere|Sphere} entity.
+ * Deprecated: Use local {@link Entities} instead.
* @typedef {object} Overlays.OverlayProperties-Sphere
* @property {string} name - The name of the overlay.
* @property {Color} color=255,255,255 - The color of the overlay.
- * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0.
+ * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 – 1.0.
* @property {number} pulseMax=0 - The maximum value of the pulse multiplier.
* @property {number} pulseMin=0 - The minimum value of the pulse multiplier.
* @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from
@@ -1514,24 +1566,34 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) {
* parentID set, otherwise the same value as position.
* @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a
* parentID set, otherwise the same value as rotation. Synonym: localOrientation.
- * @property {boolean} isSolid=false - Synonyms: solid, isFilled, and filled.
+ * @property {boolean} isSolid=false - true if the overlay is rendered as a solid, false if it is
+ * rendered as a wire frame.
+ * Synonyms: solid, isFilled, and filled.
* Antonyms: isWire and wire.
- * @property {boolean} ignorePickIntersection=false - If true, picks ignore the overlay. ignoreRayIntersection is a synonym.
- * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of objects in the world, but behind the HUD.
- * @property {boolean} drawHUDLayer=false - If true, the overlay is rendered in front of everything, including the HUD.
- * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed.
+ * @property {boolean} ignorePickIntersection=false - true if {@link Picks} ignore the overlay, false
+ * if they don't.
+ * Synonym: ignoreRayIntersection.
+ * @property {boolean} drawInFront=false - true if the overlay is rendered on top of the world layer but behind
+ * the HUD surface.
+ * @property {boolean} drawHUDLayer=false - true if the overlay is rendered in front of everything, including the
+ * HUD surface.
+ * @property {boolean} grabbable=false - true if the overlay can be grabbed, false if it can't be.
* @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to.
- * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if
- * parentID is an avatar skeleton. A value of 65535 means "no joint".
- *
+ * @property {number} parentJointIndex=65535 - Integer value specifying the joint of the entity or avatar that the entity is
+ * parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather
+ * than a joint.
*/
/**jsdoc
- * The "Rectangle3D" {@link Overlays.OverlayType|OverlayType} is for 3D rectangles.
+ * The "rectangle3D" {@link Overlays.OverlayType|OverlayType} is for 3D rectangles.
+ * It has properties in addition to the common {@link Overlays.OverlayProperties|OverlayProperties}.
+ * It additionally has properties per the {@link Entities.EntityProperties-Shape|Shape} entity, with the shape
+ * property value being "Quad".
+ * Deprecated: Use local {@link Entities} instead.
* @typedef {object} Overlays.OverlayProperties-Rectangle3D
* @property {string} name - The name of the overlay.
* @property {Color} color=255,255,255 - The color of the overlay.
- * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0.
+ * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 – 1.0.
* @property {number} pulseMax=0 - The maximum value of the pulse multiplier.
* @property {number} pulseMin=0 - The minimum value of the pulse multiplier.
* @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from
@@ -1553,20 +1615,27 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) {
* parentID set, otherwise the same value as position.
* @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a
* parentID set, otherwise the same value as rotation. Synonym: localOrientation.
- * @property {boolean} isSolid=false - Synonyms: solid, isFilled, and filled.
+ * @property {boolean} isSolid=false - true if the overlay is rendered as a solid, false if it is
+ * rendered as a wire frame.
+ * Synonyms: solid, isFilled, and filled.
* Antonyms: isWire and wire.
- * @property {boolean} ignorePickIntersection=false - If true, picks ignore the overlay. ignoreRayIntersection is a synonym.
- * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of objects in the world, but behind the HUD.
- * @property {boolean} drawHUDLayer=false - If true, the overlay is rendered in front of everything, including the HUD.
- * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed.
+ * @property {boolean} ignorePickIntersection=false - true if {@link Picks} ignore the overlay, false
+ * if they don't.
+ * Synonym: ignoreRayIntersection.
+ * @property {boolean} drawInFront=false - true if the overlay is rendered on top of the world layer but behind
+ * the HUD surface.
+ * @property {boolean} drawHUDLayer=false - true if the overlay is rendered in front of everything, including the
+ * HUD surface.
+ * @property {boolean} grabbable=false - true if the overlay can be grabbed, false if it can't be.
* @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to.
- * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if
- * parentID is an avatar skeleton. A value of 65535 means "no joint".
- *
+ * @property {number} parentJointIndex=65535 - Integer value specifying the joint of the entity or avatar that the entity is
+ * parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather
+ * than a joint.
*/
/**jsdoc
- * A shape {@link Overlays.OverlayType|OverlayType} may display as one of the following geometrical shapes:
+ * A "shape" {@link Overlays.OverlayType|OverlayType} may display as one of the following geometrical
+ * shapes:
*
*
* | Value | Dimensions | Description |
|---|
@@ -1579,7 +1648,6 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) {
* "Dodecahedron" | 3D | |
* "Hexagon" | 3D | A hexagonal prism. |
* "Icosahedron" | 3D | |
- * "Line" | 1D | A line oriented in 3D. |
* "Octagon" | 3D | An octagonal prism. |
* "Octahedron" | 3D | |
* "Quad" | 2D | A square oriented in 3D. |
@@ -1593,11 +1661,14 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) {
*/
/**jsdoc
- * The "Shape" {@link Overlays.OverlayType|OverlayType} is for 3D shapes.
+ * The "shape" {@link Overlays.OverlayType|OverlayType} is for 3D shapes.
+ * It has properties in addition to the common {@link Overlays.OverlayProperties|OverlayProperties}.
+ * It additionally has properties per the {@link Entities.EntityProperties-Shape|Shape} entity.
+ * Deprecated: Use local {@link Entities} instead.
* @typedef {object} Overlays.OverlayProperties-Shape
* @property {string} name - The name of the overlay.
* @property {Color} color=255,255,255 - The color of the overlay.
- * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0.
+ * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 – 1.0.
* @property {number} pulseMax=0 - The maximum value of the pulse multiplier.
* @property {number} pulseMin=0 - The minimum value of the pulse multiplier.
* @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from
@@ -1619,21 +1690,31 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) {
* parentID set, otherwise the same value as position.
* @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a
* parentID set, otherwise the same value as rotation. Synonym: localOrientation.
- * @property {boolean} isSolid=false - Synonyms: solid, isFilled, and filled.
+ * @property {boolean} isSolid=false - true if the overlay is rendered as a solid, false if it is
+ * rendered as a wire frame.
+ * Synonyms: solid, isFilled, and filled.
* Antonyms: isWire and wire.
- * @property {boolean} ignorePickIntersection=false - If true, picks ignore the overlay. ignoreRayIntersection is a synonym.
- * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of objects in the world, but behind the HUD.
- * @property {boolean} drawHUDLayer=false - If true, the overlay is rendered in front of everything, including the HUD.
- * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed.
+ * @property {boolean} ignorePickIntersection=false - true if {@link Picks} ignore the overlay, false
+ * if they don't.
+ * Synonym: ignoreRayIntersection.
+ * @property {boolean} drawInFront=false - true if the overlay is rendered on top of the world layer but behind
+ * the HUD surface.
+ * @property {boolean} drawHUDLayer=false - true if the overlay is rendered in front of everything, including the
+ * HUD surface.
+ * @property {boolean} grabbable=false - true if the overlay can be grabbed, false if it can't be.
* @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to.
- * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if
- * parentID is an avatar skeleton. A value of 65535 means "no joint".
+ * @property {number} parentJointIndex=65535 - Integer value specifying the joint of the entity or avatar that the entity is
+ * parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather
+ * than a joint.
*
* @property {Overlays.Shape} shape=Hexagon - The geometrical shape of the overlay.
*/
/**jsdoc
- * The "Model" {@link Overlays.OverlayType|OverlayType} is for 3D models.
+ * The "model" {@link Overlays.OverlayType|OverlayType} is for 3D models.
+ * It has properties in addition to the common {@link Overlays.OverlayProperties|OverlayProperties}.
+ * It additionally has properties per the {@link Entities.EntityProperties-Model|Model} entity.
+ * Deprecated: Use local {@link Entities} instead.
* @typedef {object} Overlays.OverlayProperties-Model
* @property {string} name - The name of the overlay.
*
@@ -1646,42 +1727,39 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) {
* parentID set, otherwise the same value as position.
* @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a
* parentID set, otherwise the same value as rotation. Synonym: localOrientation.
- * @property {boolean} ignorePickIntersection=false - If true, picks ignore the overlay. ignoreRayIntersection is a synonym.
- * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of objects in the world, but behind the HUD.
- * @property {boolean} drawHUDLayer=false - If true, the overlay is rendered in front of everything, including the HUD.
- * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed.
+ * @property {boolean} ignorePickIntersection=false - true if {@link Picks} ignore the overlay, false
+ * if they don't.
+ * Synonym: ignoreRayIntersection.
+ * @property {boolean} drawInFront=false - true if the overlay is rendered on top of the world layer but behind
+ * the HUD surface.
+ * @property {boolean} drawHUDLayer=false - true if the overlay is rendered in front of everything, including the
+ * HUD surface.
+ * @property {boolean} grabbable=false - true if the overlay can be grabbed, false if it can't be.
* @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to.
- * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if
- * parentID is an avatar skeleton. A value of 65535 means "no joint".
+ * @property {number} parentJointIndex=65535 - Integer value specifying the joint of the entity or avatar that the entity is
+ * parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather
+ * than a joint.
*
* @property {string} url - The URL of the FBX or OBJ model used for the overlay.
* @property {number} loadPriority=0.0 - The priority for loading and displaying the overlay. Overlays with higher values load
- * first.
- * @property {object.} textures - Maps the named textures in the model to the JPG or PNG images in the urls.
- * @property {string[]} jointNames - The names of the joints - if any - in the model. Read-only.
- * @property {Quat[]} jointRotations - The relative rotations of the model's joints.
- * @property {Vec3[]} jointTranslations - The relative translations of the model's joints.
- * @property {Quat[]} jointOrientations - The absolute orientations of the model's joints, in world coordinates. Read-only.
- * @property {Vec3[]} jointPositions - The absolute positions of the model's joints, in world coordinates. Read-only.
- * @property {string} animationSettings.url="" - The URL of an FBX file containing an animation to play.
- * @property {number} animationSettings.fps=0 - The frame rate (frames/sec) to play the animation at.
- * @property {number} animationSettings.firstFrame=0 - The frame to start playing at.
- * @property {number} animationSettings.lastFrame=0 - The frame to finish playing at.
- * @property {number} animationSettings.currentFrame=0 - The current frame being played.
- * @property {boolean} animationSettings.running=false - Whether or not the animation is playing.
- * @property {boolean} animationSettings.loop=false - Whether or not the animation should repeat in a loop.
- * @property {boolean} animationSettings.hold=false - Whether or not when the animation finishes, the rotations and
- * translations of the last frame played should be maintained.
- * @property {boolean} animationSettings.allowTranslation=false - Whether or not translations contained in the animation should
- * be played.
+ * first. Currently not used.
+ * @property {Object.|string} textures - Texture name, URL pairs used when rendering the model in place of the
+ * model's original textures, per the {@link Entities.EntityProperties-Model} property of the same name.
+ * The value can be an object or a JSON string when setting the value; it is a JSON string when getting the value.
+ * @property {Entities.AnimationProperties} animationSettings - An animation to play on the model.
*/
/**jsdoc
- * The "Text3D" {@link Overlays.OverlayType|OverlayType} is for 3D text.
+ * The "text3D" {@link Overlays.OverlayType|OverlayType} is for 3D text.
+ * It has properties in addition to the common {@link Overlays.OverlayProperties|OverlayProperties}.
+ * It additionally has properties per the {@link Entities.EntityProperties-Text|Text} entity.
+ * Deprecated: Use local {@link Entities} instead.
* @typedef {object} Overlays.OverlayProperties-Text3D
* @property {string} name - The name of the overlay.
- * @property {Color} color=255,255,255 - The color of the overlay.
- * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0.
+ * @property {Color} color=255,255,255 - The color of the overlay text. Synonym: textColor.
+ * @property {number} alpha=0.7 - The opacity of the overlay text, 0.0 – 1.0.
+ * Currently not used; use textAlpha instead.
+ *
* @property {number} pulseMax=0 - The maximum value of the pulse multiplier.
* @property {number} pulseMin=0 - The minimum value of the pulse multiplier.
* @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from
@@ -1703,33 +1781,29 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) {
* parentID set, otherwise the same value as position.
* @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a
* parentID set, otherwise the same value as rotation. Synonym: localOrientation.
- * @property {boolean} ignorePickIntersection=false - If true, picks ignore the overlay. ignoreRayIntersection is a synonym.
- * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of objects in the world, but behind the HUD.
- * @property {boolean} drawHUDLayer=false - If true, the overlay is rendered in front of everything, including the HUD.
- * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed.
+ * @property {boolean} ignorePickIntersection=false - true if {@link Picks} ignore the overlay, false
+ * if they don't.
+ * Synonym: ignoreRayIntersection.
+ * @property {boolean} drawInFront=false - true if the overlay is rendered on top of the world layer but behind
+ * the HUD surface.
+ * @property {boolean} drawHUDLayer=false - true if the overlay is rendered in front of everything, including the
+ * HUD surface.
+ * @property {boolean} grabbable=false - true if the overlay can be grabbed, false if it can't be.
* @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to.
- * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if
- * parentID is an avatar skeleton. A value of 65535 means "no joint".
- *
- * @property {boolean} isFacingAvatar - If true, the overlay is rotated to face the user's camera about an axis
- * parallel to the user's avatar's "up" direction.
- * @property {string} text="" - The text to display.Text does not automatically wrap; use \n for a line break.
- * @property {number} textAlpha=1 - The text alpha value.
- * @property {Color} backgroundColor=0,0,0 - The background color.
- * @property {number} backgroundAlpha=0.7 - The background alpha value.
- * @property {number} lineHeight=1 - The height of a line of text in meters.
- * @property {number} leftMargin=0.1 - The left margin, in meters.
- * @property {number} topMargin=0.1 - The top margin, in meters.
- * @property {number} rightMargin=0.1 - The right margin, in meters.
- * @property {number} bottomMargin=0.1 - The bottom margin, in meters.
+ * @property {number} parentJointIndex=65535 - Integer value specifying the joint of the entity or avatar that the entity is
+ * parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather
+ * than a joint.
*/
/**jsdoc
- * The "Image3D" {@link Overlays.OverlayType|OverlayType} is for 3D images.
+ * The "image3D" {@link Overlays.OverlayType|OverlayType} is for 3D images.
+ * It has properties in addition to the common {@link Overlays.OverlayProperties|OverlayProperties}.
+ * It additionally has properties per the {@link Entities.EntityProperties-Image|Image} entity.
+ * Deprecated: Use local {@link Entities} instead.
* @typedef {object} Overlays.OverlayProperties-Image3D
* @property {string} name - The name of the overlay.
* @property {Color} color=255,255,255 - The color of the overlay.
- * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0.
+ * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 – 1.0.
* @property {number} pulseMax=0 - The maximum value of the pulse multiplier.
* @property {number} pulseMin=0 - The minimum value of the pulse multiplier.
* @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from
@@ -1751,29 +1825,31 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) {
* parentID set, otherwise the same value as position.
* @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a
* parentID set, otherwise the same value as rotation. Synonym: localOrientation.
- * @property {boolean} ignorePickIntersection=false - If true, picks ignore the overlay. ignoreRayIntersection is a synonym.
- * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of objects in the world, but behind the HUD.
- * @property {boolean} drawHUDLayer=false - If true, the overlay is rendered in front of everything, including the HUD.
- * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed.
+ * @property {boolean} ignorePickIntersection=false - true if {@link Picks} ignore the overlay, false
+ * if they don't.
+ * Synonym: ignoreRayIntersection.
+ * @property {boolean} drawInFront=false - true if the overlay is rendered on top of the world layer but behind
+ * the HUD surface.
+ * @property {boolean} drawHUDLayer=false - true if the overlay is rendered in front of everything, including the
+ * HUD surface.
+ * @property {boolean} grabbable=false - true if the overlay can be grabbed, false if it can't be.
* @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to.
- * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if
- * parentID is an avatar skeleton. A value of 65535 means "no joint".
+ * @property {number} parentJointIndex=65535 - Integer value specifying the joint of the entity or avatar that the entity is
+ * parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather
+ * than a joint.
*
- * @property {boolean} isFacingAvatar - If true, the overlay is rotated to face the user's camera about an axis
- * parallel to the user's avatar's "up" direction.
- * @property {string} url - The URL of the PNG or JPG image to display.
- * @property {Rect} subImage - The portion of the image to display. Defaults to the full image.
- * @property {boolean} emissive - If true, the overlay is displayed at full brightness, otherwise it is rendered
- * with scene lighting.
- * @property {bool} keepAspectRatio=true - overlays will maintain the aspect ratio when the subImage is applied.
+ * @property {string} url - The URL of the image to display.
*/
/**jsdoc
- * The "Web" {@link Overlays.OverlayType|OverlayType} is for 3D web surfaces.
- * @typedef {object} Overlays.OverlayProperties-Web
+ * The "web3d" {@link Overlays.OverlayType|OverlayType} is for 3D web surfaces.
+ * It has properties in addition to the common {@link Overlays.OverlayProperties|OverlayProperties}.
+ * It additionally has properties per the {@link Entities.EntityProperties-Web|Web} entity.
+ * Deprecated: Use local {@link Entities} instead.
+ * @typedef {object} Overlays.OverlayProperties-Web3D
* @property {string} name - The name of the overlay.
* @property {Color} color=255,255,255 - The color of the overlay.
- * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0.
+ * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 – 1.0.
* @property {number} pulseMax=0 - The maximum value of the pulse multiplier.
* @property {number} pulseMin=0 - The minimum value of the pulse multiplier.
* @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from
@@ -1795,29 +1871,31 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) {
* parentID set, otherwise the same value as position.
* @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a
* parentID set, otherwise the same value as rotation. Synonym: localOrientation.
- * @property {boolean} ignorePickIntersection=false - If true, picks ignore the overlay. ignoreRayIntersection is a synonym.
- * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of objects in the world, but behind the HUD.
- * @property {boolean} drawHUDLayer=false - If true, the overlay is rendered in front of everything, including the HUD.
- * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed.
+ * @property {boolean} ignorePickIntersection=false - true if {@link Picks} ignore the overlay, false
+ * if they don't.
+ * Synonym: ignoreRayIntersection.
+ * @property {boolean} drawInFront=false - true if the overlay is rendered on top of the world layer but behind
+ * the HUD surface.
+ * @property {boolean} drawHUDLayer=false - true if the overlay is rendered in front of everything, including the
+ * HUD surface.
+ * @property {boolean} grabbable=false - true if the overlay can be grabbed, false if it can't be.
* @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to.
- * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if
- * parentID is an avatar skeleton. A value of 65535 means "no joint".
+ * @property {number} parentJointIndex=65535 - Integer value specifying the joint of the entity or avatar that the entity is
+ * parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather
+ * than a joint.
*
- * @property {boolean} isFacingAvatar - If true, the overlay is rotated to face the user's camera about an axis
- * parallel to the user's avatar's "up" direction.
- * @property {string} url - The URL of the Web page to display.
- * @property {string} scriptURL="" - The URL of a JavaScript file to inject into the Web page.
- * @property {number} dpi=30 - The dots per inch to display the Web page at, on the overlay.
- * @property {number} maxFPS=10 - The maximum update rate for the Web overlay content, in frames/second.
- * @property {string} inputMode=Touch - The user input mode to use - either "Touch" or "Mouse".
+ * @property {string} url - The URL of the web page to display.
*/
/**jsdoc
- * The "Line" {@link Overlays.OverlayType|OverlayType} is for 3D lines.
- * @typedef {object} Overlays.OverlayProperties-Line
+ * The "line3d" {@link Overlays.OverlayType|OverlayType} is for 3D lines.
+ * It has properties in addition to the common {@link Overlays.OverlayProperties|OverlayProperties}.
+ * It additionally has properties per the {@link Entities.EntityProperties-PolyLine|PolyLine} entity.
+ * Deprecated: Use local {@link Entities} instead.
+ * @typedef {object} Overlays.OverlayProperties-Line3D
* @property {string} name - The name of the overlay.
* @property {Color} color=255,255,255 - The color of the overlay.
- * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0.
+ * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 – 1.0.
*
* @property {Vec3} position - The position of the overlay center. Synonyms: p1, point, and
* start.
@@ -1827,35 +1905,61 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) {
* parentID set, otherwise the same value as position.
* @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a
* parentID set, otherwise the same value as rotation. Synonym: localOrientation.
- * @property {boolean} ignorePickIntersection=false - If true, picks ignore the overlay. ignoreRayIntersection is a synonym.
- * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of objects in the world, but behind the HUD.
- * @property {boolean} drawHUDLayer=false - If true, the overlay is rendered in front of everything, including the HUD.
- * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed.
+ * @property {boolean} ignorePickIntersection=false - true if {@link Picks} ignore the overlay, false
+ * if they don't.
+ * Synonym: ignoreRayIntersection.
+ * @property {boolean} drawInFront=false - true if the overlay is rendered on top of the world layer but behind
+ * the HUD surface.
+ * @property {boolean} drawHUDLayer=false - true if the overlay is rendered in front of everything, including the
+ * HUD surface.
+ * @property {boolean} grabbable=false - true if the overlay can be grabbed, false if it can't be.
* @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to.
- * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if
- * parentID is an avatar skeleton. A value of 65535 means "no joint".
+ * @property {number} parentJointIndex=65535 - Integer value specifying the joint of the entity or avatar that the entity is
+ * parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather
+ * than a joint.
*
* @property {Uuid} endParentID=null - The avatar, entity, or overlay that the end point of the line is parented to.
+ * Currently doesn't work.
+ *
* @property {number} endParentJointIndex=65535 - Integer value specifying the skeleton joint that the end point of the line is
- * attached to if parentID is an avatar skeleton. A value of 65535 means "no joint".
+ * attached to if parentID is an avatar skeleton. A value of 65535 means "no joint".
+ * Currently doesn't work.
+ *
+
* @property {Vec3} start - The start point of the line. Synonyms: startPoint and p1.
+ * If parentID is set, use localStart to set the local position of the start point.
+ *
* @property {Vec3} end - The end point of the line. Synonyms: endPoint and p2.
+ * If parentID is set, use localEnd to set the local position of the end point.
+ *
+
* @property {Vec3} localStart - The local position of the overlay relative to its parent if the overlay has a
- * parentID set, otherwise the same value as start. Synonym: localPosition.
+ * parentID set, otherwise the same value as start.
+ *
* @property {Vec3} localEnd - The local position of the overlay relative to its parent if the overlay has a
- * endParentID set, otherwise the same value as end.
+ * endParentID set, otherwise the same value as end.
+ *
+
* @property {number} length - The length of the line, in meters. This can be set after creating a line with start and end
- * points.
+ * points.
+ * Currently doesn't work.
+ *
+
* @property {number} glow=0 - If glow > 0, the line is rendered with a glow.
* @property {number} lineWidth=0.02 - Width of the line, in meters.
+ * You can set this property's value but currently cannot retrieve its value. Use the strokeWidths
+ * property to retrieve its value instead.
*/
/**jsdoc
- * The "Grid" {@link Overlays.OverlayType|OverlayType} is for 3D grid.
+ * The "grid" {@link Overlays.OverlayType|OverlayType} is for 3D grids.
+ * It has properties in addition to the common {@link Overlays.OverlayProperties|OverlayProperties}.
+ * It additionally has properties per the {@link Entities.EntityProperties-Grid|Grid} entity.
+ * Deprecated: Use local {@link Entities} instead.
* @typedef {object} Overlays.OverlayProperties-Grid
* @property {string} name - The name of the overlay.
* @property {Color} color=255,255,255 - The color of the overlay.
- * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0.
+ * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 – 1.0.
* @property {number} pulseMax=0 - The maximum value of the pulse multiplier.
* @property {number} pulseMin=0 - The minimum value of the pulse multiplier.
* @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from
@@ -1877,25 +1981,28 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) {
* parentID set, otherwise the same value as position.
* @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a
* parentID set, otherwise the same value as rotation. Synonym: localOrientation.
- * @property {boolean} ignorePickIntersection=false - If true, picks ignore the overlay. ignoreRayIntersection is a synonym.
- * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of objects in the world, but behind the HUD.
- * @property {boolean} drawHUDLayer=false - If true, the overlay is rendered in front of everything, including the HUD.
- * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed.
+ * @property {boolean} ignorePickIntersection=false - true if {@link Picks} ignore the overlay, false
+ * if they don't.
+ * Synonym: ignoreRayIntersection.
+ * @property {boolean} drawInFront=false - true if the overlay is rendered on top of the world layer but behind
+ * the HUD surface.
+ * @property {boolean} drawHUDLayer=false - true if the overlay is rendered in front of everything, including the
+ * HUD surface.
+ * @property {boolean} grabbable=false - true if the overlay can be grabbed, false if it can't be.
* @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to.
- * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if
- * parentID is an avatar skeleton. A value of 65535 means "no joint".
- *
- * @property {boolean} followCamera=true - If true, the grid is always visible even as the camera moves to another position.
- * @property {number} majorGridEvery=5 - Integer number of minorGridEvery intervals at which to draw a thick grid line. Minimum value = 1.
- * @property {number} minorGridEvery=1 - Real number of meters at which to draw thin grid lines. Minimum value = 0.001.
+ * @property {number} parentJointIndex=65535 - Integer value specifying the joint of the entity or avatar that the entity is
+ * parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather
+ * than a joint.
*/
/**jsdoc
- * The "Circle" {@link Overlays.OverlayType|OverlayType} is for 3D circle.
- * @typedef {object} Overlays.OverlayProperties-Circle
+ * The "circle3d" {@link Overlays.OverlayType|OverlayType} is for 3D circles.
+ * It has properties in addition to the common {@link Overlays.OverlayProperties|OverlayProperties}.
+ * It additionally has properties per the {@link Entities.EntityProperties-Gizmo|Gizmo} entity, with the
+ * gizmoType property value being "ring".
+ * Deprecated: Use local {@link Entities} instead.
+ * @typedef {object} Overlays.OverlayProperties-Circle3D
* @property {string} name - The name of the overlay.
- * @property {Color} color=255,255,255 - The color of the overlay.
- * @property {number} alpha=0.7 - The opacity of the overlay, 0.0 - 1.0.
* @property {number} pulseMax=0 - The maximum value of the pulse multiplier.
* @property {number} pulseMin=0 - The minimum value of the pulse multiplier.
* @property {number} pulsePeriod=1 - The duration of the color and alpha pulse, in seconds. A pulse multiplier value goes from
@@ -1912,62 +2019,75 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) {
* @property {Vec3} position - The position of the overlay center. Synonyms: p1, point, and
* start.
* @property {Vec3} dimensions - The dimensions of the overlay. Synonyms: scale, size.
+ * Read-only.
* @property {Quat} rotation - The orientation of the overlay. Synonym: orientation.
* @property {Vec3} localPosition - The local position of the overlay relative to its parent if the overlay has a
* parentID set, otherwise the same value as position.
* @property {Quat} localRotation - The orientation of the overlay relative to its parent if the overlay has a
* parentID set, otherwise the same value as rotation. Synonym: localOrientation.
- * @property {boolean} isSolid=false - Synonyms: solid, isFilled, and filled.
+ * @property {boolean} isSolid=false - true if the overlay is rendered as a solid, false if it is
+ * rendered as a wire frame.
+ * Synonyms: solid, isFilled, and filled.
* Antonyms: isWire and wire.
- * @property {boolean} ignorePickIntersection=false - If true, picks ignore the overlay. ignoreRayIntersection is a synonym.
- * @property {boolean} drawInFront=false - If true, the overlay is rendered in front of objects in the world, but behind the HUD.
- * @property {boolean} drawHUDLayer=false - If true, the overlay is rendered in front of everything, including the HUD.
- * @property {boolean} grabbable=false - Signal to grabbing scripts whether or not this overlay can be grabbed.
+ * @property {boolean} ignorePickIntersection=false - true if {@link Picks} ignore the overlay, false
+ * if they don't.
+ * Synonym: ignoreRayIntersection.
+ * @property {boolean} drawInFront=false - true if the overlay is rendered on top of the world layer but behind
+ * the HUD surface.
+ * @property {boolean} drawHUDLayer=false - true if the overlay is rendered in front of everything, including the
+ * HUD surface.
+ * @property {boolean} grabbable=false - true if the overlay can be grabbed, false if it can't be.
* @property {Uuid} parentID=null - The avatar, entity, or overlay that the overlay is parented to.
- * @property {number} parentJointIndex=65535 - Integer value specifying the skeleton joint that the overlay is attached to if
- * parentID is an avatar skeleton. A value of 65535 means "no joint".
+ * @property {number} parentJointIndex=65535 - Integer value specifying the joint of the entity or avatar that the entity is
+ * parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather
+ * than a joint.
*
- * @property {number} startAt = 0 - The counter - clockwise angle from the overlay's x-axis that drawing starts at in degrees.
- * @property {number} endAt = 360 - The counter - clockwise angle from the overlay's x-axis that drawing ends at in degrees.
- * @property {number} outerRadius = 1 - The outer radius of the overlay in meters. Synonym: radius.
- * @property {number} innerRadius = 0 - The inner radius of the overlay in meters.
- * @property {Color} color = 255, 255, 255 - The color of the overlay. Setting this value also sets the values of
- * innerStartColor, innerEndColor, outerStartColor, and outerEndColor.
+ * @property {number} startAt=0 - The counter-clockwise angle from the overlay's x-axis that drawing starts at, in degrees.
+ * @property {number} endAt=360 - The counter-clockwise angle from the overlay's x-axis that drawing ends at, in degrees.
+ * @property {number} outerRadius=1 - The outer radius of the overlay in meters. Synonym: radius.
+ * @property {number} innerRadius=0 - The inner radius of the overlay in meters.
+ * @property {Color} color - Sets the color of the overlay. Setting this value sets the values of innerStartColor,
+ * innerEndColor, outerStartColor, and outerEndColor.
+ * Write-only.
* @property {Color} startColor - Sets the values of innerStartColor and outerStartColor.
- * Write - only.
+ * Write-only.
* @property {Color} endColor - Sets the values of innerEndColor and outerEndColor.
- * Write - only.
+ * Write-only.
* @property {Color} innerColor - Sets the values of innerStartColor and innerEndColor.
- * Write - only.
+ * Write-only.
* @property {Color} outerColor - Sets the values of outerStartColor and outerEndColor.
- * Write - only.
- * @property {Color} innerStartcolor - The color at the inner start point of the overlay.
- * @property {Color} innerEndColor - The color at the inner end point of the overlay.
- * @property {Color} outerStartColor - The color at the outer start point of the overlay.
- * @property {Color} outerEndColor - The color at the outer end point of the overlay.
- * @property {number} alpha = 0.5 - The opacity of the overlay, 0.0 -1.0. Setting this value also sets
- * the values of innerStartAlpha, innerEndAlpha, outerStartAlpha, and
- * outerEndAlpha. Synonym: Alpha; write - only.
+ * Write-only.
+ * @property {Color} innerStartcolor=255,255,255 - The color at the inner start point of the overlay.
+ * @property {Color} innerEndColor=255,255,255 - The color at the inner end point of the overlay.
+ * @property {Color} outerStartColor=255,255,255 - The color at the outer start point of the overlay.
+ * @property {Color} outerEndColor=255,255,255 - The color at the outer end point of the overlay.
+ * @property {number} alpha - Sets the opacity of the overlay, 0.0 – 1.0. Setting this value
+ * sets the values of innerStartAlpha, innerEndAlpha, outerStartAlpha, and
+ * outerEndAlpha. Synonym: Alpha.
* @property {number} startAlpha - Sets the values of innerStartAlpha and outerStartAlpha.
- * Write - only.
+ * Write-only.
* @property {number} endAlpha - Sets the values of innerEndAlpha and outerEndAlpha.
- * Write - only.
+ * Write-only.
* @property {number} innerAlpha - Sets the values of innerStartAlpha and innerEndAlpha.
- * Write - only.
+ * Write-only.
* @property {number} outerAlpha - Sets the values of outerStartAlpha and outerEndAlpha.
- * Write - only.
- * @property {number} innerStartAlpha = 0 - The alpha at the inner start point of the overlay.
- * @property {number} innerEndAlpha = 0 - The alpha at the inner end point of the overlay.
- * @property {number} outerStartAlpha = 0 - The alpha at the outer start point of the overlay.
- * @property {number} outerEndAlpha = 0 - The alpha at the outer end point of the overlay.
+ * Write-only.
+ * @property {number} innerStartAlpha=0.7 - The opacity at the inner start point of the overlay, 0.0 –
+ * 1.0.
+ * @property {number} innerEndAlpha=0.7 - The opacity at the inner end point of the overlay, 0.0 –
+ * 1.0.
+ * @property {number} outerStartAlpha=0.7 - The opacity at the outer start point of the overlay, 0.0 –
+ * 1.0.
+ * @property {number} outerEndAlpha=0.7 - The opacity at the outer end point of the overlay, 0.0 –
+ * 1.0.
*
- * @property {boolean} hasTickMarks = false - If true, tick marks are drawn.
- * @property {number} majorTickMarksAngle = 0 - The angle between major tick marks, in degrees.
- * @property {number} minorTickMarksAngle = 0 - The angle between minor tick marks, in degrees.
- * @property {number} majorTickMarksLength = 0 - The length of the major tick marks, in meters. A positive value draws tick marks
+ * @property {boolean} hasTickMarks=false - true if tick marks are drawn, false if they aren't.
+ * @property {number} majorTickMarksAngle=0 - The angle between major tick marks, in degrees.
+ * @property {number} minorTickMarksAngle=0 - The angle between minor tick marks, in degrees.
+ * @property {number} majorTickMarksLength=0 - The length of the major tick marks, in meters. A positive value draws tick marks
* outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.
- * @property {number} minorTickMarksLength = 0 - The length of the minor tick marks, in meters. A positive value draws tick marks
+ * @property {number} minorTickMarksLength=0 - The length of the minor tick marks, in meters. A positive value draws tick marks
* outwards from the inner radius; a negative value draws tick marks inwards from the outer radius.
- * @property {Color} majorTickMarksColor = 0, 0, 0 - The color of the major tick marks.
- * @property {Color} minorTickMarksColor = 0, 0, 0 - The color of the minor tick marks.
+ * @property {Color} majorTickMarksColor=0,0,0 - The color of the major tick marks.
+ * @property {Color} minorTickMarksColor=0,0,0 - The color of the minor tick marks.
*/
diff --git a/interface/src/ui/overlays/Overlays.h b/interface/src/ui/overlays/Overlays.h
index 1a2382769c..739f5ba45a 100644
--- a/interface/src/ui/overlays/Overlays.h
+++ b/interface/src/ui/overlays/Overlays.h
@@ -68,17 +68,23 @@ public:
};
/**jsdoc
- * (Note: 3D Overlays are deprecated. Use local entities instead.) The Overlays API provides facilities to create and interact with overlays. Overlays are 2D and 3D objects visible only to
- * yourself and that aren't persisted to the domain. They are used for UI.
+ * The Overlays API provides facilities to create and interact with overlays. These are 2D and 3D objects visible
+ * only to yourself and that aren't persisted to the domain. They are used for UI.
+ *
+ * Note: 3D overlays are local {@link Entities}, internally, so many of the methods also work with
+ * entities.
+ *
+ * 3D overlays are deprecated: Use local {@link Entities} for these instead.
+ *
* @namespace Overlays
*
* @hifi-interface
* @hifi-client-entity
* @hifi-avatar
*
- * @property {Uuid} keyboardFocusOverlay - Get or set the {@link Entities.EntityTypes|Web} entity that has keyboard focus.
- * If no entity has keyboard focus, returns null; set to null or {@link Uuid(0)|Uuid.NULL} to
- * clear keyboard focus.
+ * @property {Uuid} keyboardFocusOverlay - The {@link Overlays.OverlayProperties-Web3D|"web3d"} overlay
+ * ({@link Entities.EntityProperties-Web|Web} entity) that has keyboard focus. If no overlay (entity) has keyboard focus,
+ * returns null; set to null or {@link Uuid(0)|Uuid.NULL} to clear keyboard focus.
*/
class Overlays : public QObject {
@@ -118,7 +124,7 @@ public:
public slots:
/**jsdoc
- * Add an overlay to the scene.
+ * Adds an overlay to the scene.
* @function Overlays.addOverlay
* @param {Overlays.OverlayType} type - The type of the overlay to add.
* @param {Overlays.OverlayProperties} properties - The properties of the overlay to add.
@@ -134,19 +140,21 @@ public slots:
QUuid addOverlay(const QString& type, const QVariant& properties);
/**jsdoc
- * Create a clone of an existing entity (or 2D overlay).
+ * Creates a clone of an existing overlay (or entity).
+ * Note: For cloning behavior of 3D overlays and entities, see {@link Entities.cloneEntity}.
* @function Overlays.cloneOverlay
- * @param {Uuid} id - The ID of the entity/2D overlay to clone.
- * @returns {Uuid} The ID of the new object if successful, otherwise {@link Uuid(0)|Uuid.NULL}.
+ * @param {Uuid} id - The ID of the overlay (or entity) to clone.
+ * @returns {Uuid} The ID of the new overlay (or entity) if successful, otherwise {@link Uuid(0)|Uuid.NULL}.
*/
QUuid cloneOverlay(const QUuid& id);
/**jsdoc
- * Edit an overlay's properties.
+ * Edits an overlay's (or entity's) properties.
* @function Overlays.editOverlay
- * @param {Uuid} id - The ID of the overlay to edit.
+ * @param {Uuid} id - The ID of the overlay (or entity) to edit.
* @param {Overlays.OverlayProperties} properties - The properties changes to make.
- * @returns {boolean} true if the overlay was found and edited, otherwise false.
+ * @returns {boolean} false if Interface is exiting. Otherwise, if a 2D overlay then true always,
+ * and if a 3D overlay then true if the overlay was found and edited, otherwise false.
* @example Add an overlay in front of your avatar then change its color.
* var overlay = Overlays.addOverlay("cube", {
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })),
@@ -163,12 +171,11 @@ public slots:
bool editOverlay(const QUuid& id, const QVariant& properties);
/**jsdoc
- * Edit multiple overlays' properties.
+ * Edits the properties of multiple overlays (or entities).
* @function Overlays.editOverlays
- * @param propertiesById {object.} - An object with overlay IDs as keys and
+ * @param propertiesById {object.} - An object with overlay (or entity) IDs as keys and
* {@link Overlays.OverlayProperties|OverlayProperties} edits to make as values.
- * @returns {boolean} true if all overlays were found and edited, otherwise false (some may have
- * been found and edited).
+ * @returns {boolean} false if Interface is exiting, otherwise true.
* @example Create two overlays in front of your avatar then change their colors.
* var overlayA = Overlays.addOverlay("cube", {
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: -0.3, y: 0, z: -3 })),
@@ -192,18 +199,18 @@ public slots:
bool editOverlays(const QVariant& propertiesById);
/**jsdoc
- * Delete an entity or 2D overlay.
+ * Deletes an overlay (or entity).
* @function Overlays.deleteOverlay
- * @param {Uuid} id - The ID of the object to delete.
+ * @param {Uuid} id - The ID of the overlay (or entity) to delete.
*/
void deleteOverlay(const QUuid& id);
/**jsdoc
- * Get the type of an entity or 2D overlay.
+ * Gets the type of an overlay.
* @function Overlays.getOverlayType
- * @param {Uuid} id - The ID of the object to get the type of.
- * @returns {string} The type of the object if found, otherwise an empty string.
- * @example Create an object in front of your avatar then get and report its type.
+ * @param {Uuid} id - The ID of the overlay to get the type of.
+ * @returns {Overlays.OverlayType} The type of the overlay if found, otherwise "unknown".
+ * @example Create an overlay in front of your avatar then get and report its type.
* var overlay = Overlays.addOverlay("cube", {
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })),
* rotation: MyAvatar.orientation,
@@ -211,56 +218,82 @@ public slots:
* solid: true
* });
* var type = Overlays.getOverlayType(overlay);
- * print("Type: " + type);
+ * print("Type: " + type); // cube
*/
QString getOverlayType(const QUuid& id);
/**jsdoc
- * Get the overlay script object. In particular, this is useful for accessing the event bridge for a web3d
- * overlay.
+ * Gets an overlay's (or entity's) script object. In particular, this is useful for accessing a
+ * {@link Overlays.OverlayProperties-Web3D|"web3d"} overlay's EventBridge script object to
+ * exchange messages with the web page script.
+ * To send a message from an Interface script to a "web3d" overlay over its event bridge:
+ * var overlayObject = Overlays.getOverlayObject(overlayID);
+ * overlayObject.emitScriptEvent(message);
+ * To receive a message from a "web3d" overlay over its event bridge in an Interface script:
+ * var overlayObject = Overlays.getOverlayObject(overlayID);
+ * overlayObject.webEventReceived.connect(function(message) {
+ * ...
+ * };
* @function Overlays.getOverlayObject
* @param {Uuid} overlayID - The ID of the overlay to get the script object of.
* @returns {object} The script object for the overlay if found.
- * @example Receive "hello" messages from a web3d overlay.
- * // HTML file: name "web3d.html".
+ * @example Exchange messages with a "web3d" overlay.
+ * // HTML file, name: "web3d.html".
*
*
*
* HELLO
*
*
- * HELLO
+ * HELLO
*
*
*
- *
- * // Script file.
- * var web3dOverlay = Overlays.addOverlay("web3d", {
- * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, {x: 0, y: 0.5, z: -3 })),
- * rotation: MyAvatar.orientation,
- * url: Script.resolvePath("web3d.html"),
- * alpha: 1.0
- * });
- *
- * function onWebEventReceived(event) {
- * print("onWebEventReceived() : " + JSON.stringify(event));
+ *
+ * // Interface script file.
+ * var web3DOverlay = Overlays.addOverlay("web3d", {
+ * type: "Web",
+ * position : Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y : 0.5, z : -3 })),
+ * rotation : MyAvatar.orientation,
+ * sourceUrl : Script.resolvePath("web3d.html"),
+ * alpha : 1.0
+ * });
+ *
+ * var overlayObject;
+ *
+ * function onWebEventReceived(message) {
+ * // Message received.
+ * print("Message received: " + message);
+ *
+ * // Send a message back.
+ * overlayObject.emitScriptEvent(message + " back");
* }
- *
- * overlayObject = Overlays.getOverlayObject(web3dOverlay);
- * overlayObject.webEventReceived.connect(onWebEventReceived);
- *
- * Script.scriptEnding.connect(function () {
- * Overlays.deleteOverlay(web3dOverlay);
+ *
+ * Script.setTimeout(function() {
+ * overlayObject = Overlays.getOverlayObject(web3DOverlay);
+ * overlayObject.webEventReceived.connect(onWebEventReceived);
+ * }, 500);
+ *
+ * Script.scriptEnding.connect(function() {
+ * Overlays.deleteOverlay(web3DOverlay);
* });
*/
QObject* getOverlayObject(const QUuid& id);
/**jsdoc
- * Get the ID of the 2D overlay at a particular point on the screen or HUD.
+ * Gets the ID of the 2D overlay at a particular point on the desktop screen or HUD surface.
* @function Overlays.getOverlayAtPoint
* @param {Vec2} point - The point to check for an overlay.
* @returns {Uuid} The ID of the 2D overlay at the specified point if found, otherwise null.
@@ -279,10 +312,11 @@ public slots:
QUuid getOverlayAtPoint(const glm::vec2& point);
/**jsdoc
- * Get the value of a 3D overlay's property.
+ * Gets a specified property value of a 3D overlay (or entity).
+ * Note: 2D overlays' property values cannot be retrieved.
* @function Overlays.getProperty
- * @param {Uuid} id - The ID of the overlay. Must be for a 3D {@link Overlays.OverlayType|OverlayType}.
- * @param {string} property - The name of the property value to get.
+ * @param {Uuid} id - The ID of the 3D overlay (or entity).
+ * @param {string} property - The name of the property to get the value of.
* @returns {object} The value of the property if the 3D overlay and property can be found, otherwise
* undefined.
* @example Create an overlay in front of your avatar then report its alpha property value.
@@ -298,12 +332,13 @@ public slots:
QVariant getProperty(const QUuid& id, const QString& property);
/**jsdoc
- * Get the values of an overlay's properties.
+ * Gets specified property values of a 3D overlay (or entity).
+ * Note: 2D overlays' property values cannot be retrieved.
* @function Overlays.getProperties
- * @param {Uuid} id - The ID of the overlay.
- * @param {Array.} properties - An array of names of properties to get the values of.
- * @returns {Overlays.OverlayProperties} The values of valid properties if the overlay can be found, otherwise
- * undefined.
+ * @param {Uuid} id - The ID of the overlay (or entity).
+ * @param {Array.} properties - The names of the properties to get the values of.
+ * @returns {Overlays.OverlayProperties} The values of valid properties if the overlay can be found, otherwise an empty
+ * object.
* @example Create an overlay in front of your avatar then report some of its properties.
* var overlay = Overlays.addOverlay("cube", {
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })),
@@ -317,11 +352,11 @@ public slots:
QVariantMap getProperties(const QUuid& id, const QStringList& properties);
/**jsdoc
- * Get the values of multiple overlays' properties.
+ * Gets the values of multiple overlays' (or entities') properties.
* @function Overlays.getOverlaysProperties
- * @param propertiesById {object.>} - An object with overlay IDs as keys and arrays of the names of
- * properties to get for each as values.
- * @returns {object.} An object with overlay IDs as keys and
+ * @param propertiesById {object.>} - An object with overlay (or entity) IDs as keys and arrays of the
+ * names of properties to get for each as values.
+ * @returns {object.} An object with overlay (or entity) IDs as keys and
* {@link Overlays.OverlayProperties|OverlayProperties} as values.
* @example Create two cube overlays in front of your avatar then get some of their properties.
* var overlayA = Overlays.addOverlay("cube", {
@@ -345,22 +380,20 @@ public slots:
QVariantMap getOverlaysProperties(const QVariant& overlaysProperties);
/**jsdoc
- * Find the closest 3D overlay intersected by a {@link PickRay}. Overlays with their drawInFront property set
- * to true have priority over overlays that don't, except that tablet overlays have priority over any
- * drawInFront overlays behind them. I.e., if a drawInFront overlay is behind one that isn't
- * drawInFront, the drawInFront overlay is returned, but if a tablet overlay is in front of a
- * drawInFront overlay, the tablet overlay is returned.
+ * Finds the closest 3D overlay (or local entity) intersected by a {@link PickRay}.
* @function Overlays.findRayIntersection
* @param {PickRay} pickRay - The PickRay to use for finding overlays.
- * @param {boolean} [precisionPicking=false] - Unused; exists to match Entity API.
- * @param {Array.} [include=[]] - If not empty then the search is restricted to these overlays.
- * @param {Array.} [discard=[]] - Overlays to ignore during the search.
- * @param {boolean} [visibleOnly=false] - If true then only entities that are
- * {@link Entities.EntityProperties|visible} are searched.
- * @param {boolean} [collideableOnly=false] - If true then only entities that are not
- * {@link Entities.EntityProperties|collisionless} are searched.
- * @returns {Overlays.RayToOverlayIntersectionResult} The closest 3D overlay intersected by pickRay, taking
- * into account overlayIDsToInclude and overlayIDsToExclude if they're not empty.
+ * @param {boolean} [precisionPicking=false] - true to pick against precise meshes, false to pick
+ * against coarse meshes. If true and the intersected entity is a model, the result's
+ * extraInfo property includes more information than it otherwise would.
+ * @param {Array.} [include=[]] - If not empty, then the search is restricted to these overlays (and local entities).
+ * @param {Array.} [discard=[]] - Overlays (and local entities) to ignore during the search.
+ * @param {boolean} [visibleOnly=false] - true if only overlays (and local entities) that are
+ * {@link Overlays.OverlayProperties|visible} should be searched.
+ * @param {boolean} [collideableOnly=false] - true if only local entities that are not
+ * {@link Entities.EntityProperties|collisionless} should be searched.
+ * @returns {Overlays.RayToOverlayIntersectionResult} The result of the search for the first intersected overlay (or local
+ * entity.
* @example Create a cube overlay in front of your avatar. Report 3D overlay intersection details for mouse
* clicks.
* var overlay = Overlays.addOverlay("cube", {
@@ -384,12 +417,13 @@ public slots:
bool collidableOnly = false);
/**jsdoc
- * Return a list of local entities with bounding boxes that touch a search sphere.
+ * Gets a list of visible 3D overlays (local entities) with bounding boxes that touch a search sphere.
* @function Overlays.findOverlays
* @param {Vec3} center - The center of the search sphere.
* @param {number} radius - The radius of the search sphere.
- * @returns {Uuid[]} An array of entity IDs with bounding boxes that touch a search sphere.
- * @example Create two cube entities in front of your avatar then search for entities near your avatar.
+ * @returns {Uuid[]} The IDs of the overlays (local entities) that are visible and have bounding boxes that touch a search
+ * sphere.
+ * @example Create two overlays in front of your avatar then search for overlays near your avatar.
* var overlayA = Overlays.addOverlay("cube", {
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: -0.3, y: 0, z: -3 })),
* rotation: MyAvatar.orientation,
@@ -411,11 +445,13 @@ public slots:
QVector findOverlays(const glm::vec3& center, float radius);
/**jsdoc
- * Check whether an overlay's assets have been loaded. For example, for an image overlay the result indicates
- * whether its image has been loaded.
+ * Checks whether an overlay's (or entity's) assets have been loaded. For example, for an
+ * {@link Overlays.OverlayProperties-Image|"image"} overlay, the result indicates whether its image has been
+ * loaded.
* @function Overlays.isLoaded
- * @param {Uuid} id - The ID of the overlay to check.
- * @returns {boolean} true if the overlay's assets have been loaded, otherwise false.
+ * @param {Uuid} id - The ID of the overlay (or entity) to check.
+ * @returns {boolean} true if the overlay's (or entity's) assets have been loaded, otherwise
+ * false.
* @example Create an image overlay and report whether its image is loaded after 1s.
* var overlay = Overlays.addOverlay("image", {
* bounds: { x: 100, y: 100, width: 200, height: 200 },
@@ -429,55 +465,60 @@ public slots:
bool isLoaded(const QUuid& id);
/**jsdoc
- * Calculates the size of the given text in the specified object if it is a text entity or overlay.
+ * Calculates the size of some text in a text overlay (or entity). The overlay (or entity) need not be set visible.
+ * Note: The size of text in a 3D overlay (or entity) cannot be calculated immediately after the
+ * overlay (or entity) is created; a short delay is required while the overlay (or entity) finishes being created.
* @function Overlays.textSize
- * @param {Uuid} id - The ID of the object to use for calculation.
+ * @param {Uuid} id - The ID of the overlay (or entity) to use for calculation.
* @param {string} text - The string to calculate the size of.
- * @returns {Size} The size of the text if the object is a text entity or overlay, otherwise
- * { height: 0, width : 0 }. If the object is a 2D overlay, the size is in pixels; if the object is an entity,
- * the size is in meters.
+ * @returns {Size} The size of the text if the object is a text overlay (or entity), otherwise
+ * { height: 0, width : 0 }. If the object is a 2D overlay, the size is in pixels; if the object is a 3D
+ * overlay (or entity), the size is in meters.
* @example Calculate the size of "hello" in a 3D text entity.
* var overlay = Overlays.addOverlay("text3d", {
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -2 })),
* rotation: MyAvatar.orientation,
- * text: "hello",
- * lineHeight: 0.2
+ * lineHeight: 0.2,
+ * visible: false
* });
- * var textSize = Overlays.textSize(overlay, "hello");
- * print("Size of \"hello\": " + JSON.stringify(textSize));
+ *
+ * Script.setTimeout(function() {
+ * var textSize = Overlays.textSize(overlay, "hello");
+ * print("Size of \"hello\": " + JSON.stringify(textSize));
+ * }, 500);
*/
QSizeF textSize(const QUuid& id, const QString& text);
/**jsdoc
- * Get the width of the window or HUD.
+ * Gets the width of the Interface window or HUD surface.
* @function Overlays.width
- * @returns {number} The width, in pixels, of the Interface window if in desktop mode or the HUD if in HMD mode.
+ * @returns {number} The width, in pixels, of the Interface window if in desktop mode or the HUD surface if in HMD mode.
*/
float width();
/**jsdoc
- * Get the height of the window or HUD.
+ * Gets the height of the Interface window or HUD surface.
* @function Overlays.height
- * @returns {number} The height, in pixels, of the Interface window if in desktop mode or the HUD if in HMD mode.
+ * @returns {number} The height, in pixels, of the Interface window if in desktop mode or the HUD surface if in HMD mode.
*/
float height();
/**jsdoc
- * Check if there is an object of a given ID.
+ * Checks if an overlay (or entity) exists.
* @function Overlays.isAddedOverlay
- * @param {Uuid} id - The ID to check.
- * @returns {boolean} true if an object with the given ID exists, false otherwise.
+ * @param {Uuid} id - The ID of the overlay (or entity) to check.
+ * @returns {boolean} true if an overlay (or entity) with the given ID exists, false if it doesn't.
*/
bool isAddedOverlay(const QUuid& id);
/**jsdoc
- * Generate a mouse press event on an overlay.
+ * Generates a mouse press event on an overlay (or local entity).
* @function Overlays.sendMousePressOnOverlay
- * @param {Uuid} id - The ID of the overlay to generate a mouse press event on.
+ * @param {Uuid} id - The ID of the overlay (or local entity) to generate a mouse press event on.
* @param {PointerEvent} event - The mouse press event details.
- * @example Create a 2D rectangle overlay plus a 3D cube overlay and generate mousePressOnOverlay events for the 2D
- * overlay.
- * var overlay = Overlays.addOverlay("cube", {
+ * @example Create a 2D rectangle overlay plus a 3D cube overlay and generate mousePressOnOverlay events for the
+ * 2D overlay.
+ * var overlay3D = Overlays.addOverlay("cube", {
* position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })),
* rotation: MyAvatar.orientation,
* dimensions: { x: 0.3, y: 0.3, z: 0.3 },
@@ -485,7 +526,7 @@ public slots:
* });
* print("3D overlay: " + overlay);
*
- * var overlay = Overlays.addOverlay("rectangle", {
+ * var overlay2D = Overlays.addOverlay("rectangle", {
* bounds: { x: 100, y: 100, width: 200, height: 100 },
* color: { red: 255, green: 255, blue: 255 }
* });
@@ -511,66 +552,69 @@ public slots:
void sendMousePressOnOverlay(const QUuid& id, const PointerEvent& event);
/**jsdoc
- * Generate a mouse release event on an overlay.
+ * Generates a mouse release event on an overlay (or local entity).
* @function Overlays.sendMouseReleaseOnOverlay
- * @param {Uuid} id - The ID of the overlay to generate a mouse release event on.
+ * @param {Uuid} id - The ID of the overlay (or local entity) to generate a mouse release event on.
* @param {PointerEvent} event - The mouse release event details.
*/
void sendMouseReleaseOnOverlay(const QUuid& id, const PointerEvent& event);
/**jsdoc
- * Generate a mouse move event on an overlay.
+ * Generates a mouse move event on an overlay (or local entity).
* @function Overlays.sendMouseMoveOnOverlay
- * @param {Uuid} id - The ID of the overlay to generate a mouse move event on.
+ * @param {Uuid} id - The ID of the overlay (or local entity) to generate a mouse move event on.
* @param {PointerEvent} event - The mouse move event details.
*/
void sendMouseMoveOnOverlay(const QUuid& id, const PointerEvent& event);
/**jsdoc
- * Generate a hover enter event on an overlay.
+ * Generates a hover enter event on an overlay (or local entity).
* @function Overlays.sendHoverEnterOverlay
- * @param {Uuid} id - The ID of the overlay to generate a hover enter event on.
+ * @param {Uuid} id - The ID of the overlay (or local entity) to generate a hover enter event on.
* @param {PointerEvent} event - The hover enter event details.
*/
void sendHoverEnterOverlay(const QUuid& id, const PointerEvent& event);
/**jsdoc
- * Generate a hover over event on an overlay.
+ * Generates a hover over event on an overlay (or entity).
* @function Overlays.sendHoverOverOverlay
- * @param {Uuid} id - The ID of the overlay to generate a hover over event on.
+ * @param {Uuid} id - The ID of the overlay (or local entity) to generate a hover over event on.
* @param {PointerEvent} event - The hover over event details.
*/
void sendHoverOverOverlay(const QUuid& id, const PointerEvent& event);
/**jsdoc
- * Generate a hover leave event on an overlay.
+ * Generates a hover leave event on an overlay (or local entity).
* @function Overlays.sendHoverLeaveOverlay
- * @param {Uuid} id - The ID of the overlay to generate a hover leave event on.
+ * @param {Uuid} id - The ID of the overlay (or local entity) to generate a hover leave event on.
* @param {PointerEvent} event - The hover leave event details.
*/
void sendHoverLeaveOverlay(const QUuid& id, const PointerEvent& event);
/**jsdoc
- * Get the ID of the Web3D entity that has keyboard focus.
+ * Gets the ID of the {@link Overlays.OverlayProperties-Web3D|"web3d"} overlay
+ * ({@link Entities.EntityProperties-Web|Web} entity) that has keyboard focus.
* @function Overlays.getKeyboardFocusOverlay
- * @returns {Uuid} The ID of the {@link Entities.EntityTypes|Web} overlay that has focus, if any, otherwise
- * null.
+ * @returns {Uuid} The ID of the {@link Overlays.OverlayProperties-Web3D|"web3d"} overlay
+ * ({@link Entities.EntityProperties-Web|Web} entity) that has focus, if any, otherwise null.
*/
QUuid getKeyboardFocusOverlay() { return DependencyManager::get()->getKeyboardFocusEntity(); }
/**jsdoc
- * Set the Web3D entity that has keyboard focus.
+ * Sets the {@link Overlays.OverlayProperties-Web3D|"web3d"} overlay
+ * ({@link Entities.EntityProperties-Web|Web} entity) that has keyboard focus.
* @function Overlays.setKeyboardFocusOverlay
- * @param {Uuid} id - The ID of the {@link Entities.EntityTypes|Web} entity to set keyboard focus to. Use
- * null or {@link Uuid(0)|Uuid.NULL} to unset keyboard focus from an overlay.
+ * @param {Uuid} id - The ID of the {@link Overlays.OverlayProperties-Web3D|"web3d"} overlay
+ * ({@link Entities.EntityProperties-Web|Web} entity) to set keyboard focus to. Use null or
+ * {@link Uuid(0)|Uuid.NULL} to unset keyboard focus from an overlay (entity).
*/
void setKeyboardFocusOverlay(const QUuid& id) { DependencyManager::get()->setKeyboardFocusEntity(id); }
signals:
/**jsdoc
- * Triggered when an overlay is deleted.
+ * Triggered when an overlay (or entity) is deleted.
* @function Overlays.overlayDeleted
- * @param {Uuid} id - The ID of the overlay that was deleted.
+ * @param {Uuid} id - The ID of the overlay (or entity) that was deleted.
* @returns {Signal}
* @example Create an overlay then delete it after 1s.
* var overlay = Overlays.addOverlay("cube", {
diff --git a/libraries/entities/src/EntityItemProperties.cpp b/libraries/entities/src/EntityItemProperties.cpp
index 980cd31652..b89788040f 100644
--- a/libraries/entities/src/EntityItemProperties.cpp
+++ b/libraries/entities/src/EntityItemProperties.cpp
@@ -988,8 +988,8 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const {
* false otherwise; [] if none are applied or the model hasn't loaded. The array indexes are per
* {@link Entities.getJointIndex|getJointIndex}.
* @property {Vec3[]} jointTranslations=[]] - Joint translations applied to the model; [] if none are applied or
- * the model hasn't loaded. The array indexes are per {@link Entities.getJointIndex|getJointIndex}. Rotations are relative
- * to each joint's parent.
+ * the model hasn't loaded. The array indexes are per {@link Entities.getJointIndex|getJointIndex}. Translations are
+ * relative to each joint's parent.
* Joint translations can be set by {@link Entities.setLocalJointTranslation|setLocalJointTranslation} and similar
* functions, or by setting the value of this property. If you set a joint translation using this property you also need to
* set the corresponding jointTranslationsSet value to true.
diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h
index ad2aaf2160..0442756300 100644
--- a/libraries/entities/src/EntityScriptingInterface.h
+++ b/libraries/entities/src/EntityScriptingInterface.h
@@ -446,7 +446,15 @@ public slots:
/**jsdoc
* Gets an entity's script object. In particular, this is useful for accessing a {@link Entities.EntityProperties-Web|Web}
* entity's HTML EventBridge script object to exchange messages with the web page script.
- * Alternatively, you can use {@link Entities.emitScriptEvent} and {@link Entities.webEventReceived} to exchange
+ *
To send a message from an Interface script to a Web entity over its event bridge:
+ * var entityObject = Entities.getEntityObject(entityID);
+ * entityObject.emitScriptEvent(message);
+ * To receive a message from a Web entity over its event bridge in an Interface script:
+ * var entityObject = Entities.getentityObject(entityID);
+ * entityObject.webEventReceived.connect(function(message) {
+ * ...
+ * };
+ * Alternatively, you can use {@link Entities.emitScriptEvent} and {@link Entities.webEventReceived} to exchange
* messages with a Web entity over its event bridge.
* @function Entities.getEntityObject
* @param {Uuid} id - The ID of the entity to get the script object for.
@@ -459,7 +467,7 @@ public slots:
* HELLO
*
*
- * HELLO
+ * HELLO
*