From c70d2c006f546b652050d76bb5e78b8b3549979a Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 3 Jul 2019 14:25:11 +1200 Subject: [PATCH 01/29] Revise organization of Overlays types and properties JSDoc per Entities --- interface/src/ui/overlays/Overlays.cpp | 171 +++++++++++++++++-------- interface/src/ui/overlays/Overlays.h | 11 +- 2 files changed, 124 insertions(+), 58 deletions(-) diff --git a/interface/src/ui/overlays/Overlays.cpp b/interface/src/ui/overlays/Overlays.cpp index 2ade5edda5..0532b20b0f 100644 --- a/interface/src/ui/overlays/Overlays.cpp +++ b/interface/src/ui/overlays/Overlays.cpp @@ -1333,60 +1333,99 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { *

An overlay may be one of the following types:

* * - * + * * * - * - * - * - * - * - * - * - * - * - * - * - * - * - * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * * *
Value2D/3DDescription
Value2D/3DDescriptionProperties
image2DAn image. Synonym: billboard.
rectangle2DA rectangle.
text2DText.
cube3DA cube. Can also use a shape overlay to create a cube.
sphere3DA sphere. Can also use a shape overlay to create a sphere.
rectangle3d3DA rectangle.
shape3DA geometric shape, such as a cube, sphere, or cylinder.
model3DA model.
text3d3DText.
image3d3DAn image.
web3d3DWeb content.
line3d3DA line.
grid3DA grid of lines in a plane.
circle3d3DA circle.
"image"2DAn image.{@link Overlays.OverlayProperties-Image|OverlayProperties-Image}
"rectangle"2DA rectangle.{@link Overlays.OverlayProperties-Rectangle|OverlayProperties-Rectangle}
"text"2DSome text.{@link Overlays.OverlayProperties-Text|OverlayProperties-Text}
"cube"3DA cube. A "shape" overlay can also be used to create a cube.
+ * Deprecated. + * 		{@link Overlays.OverlayProperties-Cube|OverlayProperties-Cube}
"sphere"3DA sphere. A "shape" overlay can also be used to create a sphere.
+ * Deprecated.		{@link Overlays.OverlayProperties-Sphere|OverlayProperties-Sphere}
"rectangle3d"3DA rectangle.
+ * Deprecated.		{@link Overlays.OverlayProperties-Rectangle3D|OverlayProperties-Rectangle3D}
"shape"3DA geometric shape, such as a cube, sphere, or cylinder.
+ * Deprecated.		{@link Overlays.OverlayProperties-Shape|OverlayProperties-Shape}
"model"3DA model.
+ * Deprecated.		{@link Overlays.OverlayProperties-Model|OverlayProperties-Model}
"text3d"3DSome text.
+ * Deprecated.		{@link Overlays.OverlayProperties-Text3D|OverlayProperties-Text3D}
"image3d"3DAn image. Synonym: "billboard".
+ * Deprecated.		{@link Overlays.OverlayProperties-Image3D|OverlayProperties-Image3D}
"web3d"3DWeb content.
+ * Deprecated.		{@link Overlays.OverlayProperties-Web3D|OverlayProperties-Web3D}
"line3d"3DA line.
+ * Deprecated.		{@link Overlays.OverlayProperties-Line3D|OverlayProperties-Line3D}
"grid"3DA grid of lines in a plane.
+ * Deprecated.		{@link Overlays.OverlayProperties-Grid|OverlayProperties-Grid}
"circle3d"3DA 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} for these 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 corresponding entity 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-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-Text|OverlayProperties-Text} + * @see {@link Overlays.OverlayProperties-Cube|OverlayProperties-Cube} Deprecated. + * @see {@link Overlays.OverlayProperties-Sphere|OverlayProperties-Sphere} Deprecated. + * @see {@link Overlays.OverlayProperties-Rectangle3D|OverlayProperties-Rectangle3D} Deprecated. + * @see {@link Overlays.OverlayProperties-Shape|OverlayProperties-Shape} Deprecated. + * @see {@link Overlays.OverlayProperties-Model|OverlayProperties-Model} Deprecated. + * @see {@link Overlays.OverlayProperties-Text3D|OverlayProperties-Text3D} Deprecated. + * @see {@link Overlays.OverlayProperties-Image3D|OverlayProperties-Image3D} 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. @@ -1405,7 +1444,8 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { */ /**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. @@ -1430,7 +1470,8 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { */ /**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. @@ -1449,7 +1490,9 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { */ /**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}. + *

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. @@ -1488,7 +1531,9 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { */ /**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}. + *

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. @@ -1527,7 +1572,9 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { */ /**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}. + *

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. @@ -1566,7 +1613,7 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { */ /**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:

* * * @@ -1593,7 +1640,9 @@ 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}. + *

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. @@ -1633,7 +1682,9 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { */ /**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}. + *

Deprecated: Use local {@link Entities} instead.

* @typedef {object} Overlays.OverlayProperties-Model * @property {string} name - The name of the overlay. * @@ -1677,7 +1728,9 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { */ /**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}. + *

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. @@ -1725,7 +1778,9 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { */ /**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}. + *

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. @@ -1769,8 +1824,10 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { */ /**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}. + *

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. @@ -1813,8 +1870,10 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { */ /**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}. + *

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. @@ -1851,7 +1910,9 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { */ /**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}. + *

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. @@ -1891,8 +1952,10 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { */ /**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}. + *

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. diff --git a/interface/src/ui/overlays/Overlays.h b/interface/src/ui/overlays/Overlays.h index 1a2382769c..9ff03e0c53 100644 --- a/interface/src/ui/overlays/Overlays.h +++ b/interface/src/ui/overlays/Overlays.h @@ -68,8 +68,11 @@ 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. + * + *

3D overlays are deprecated: Use local {@link Entities} for these instead.

+ * * @namespace Overlays * * @hifi-interface @@ -216,12 +219,12 @@ public slots: QString getOverlayType(const QUuid& id); /**jsdoc - * Get the overlay script object. In particular, this is useful for accessing the event bridge for a web3d + * Get the overlay script object. In particular, this is useful for accessing the event bridge for a "web3d" * overlay. * @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 + * @example * // HTML file: name "web3d.html". * * From 9f4c657bc3f02e2714151b6c83adcb1aa1a7a125 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Sat, 6 Jul 2019 12:12:33 +1200 Subject: [PATCH 02/29] Update Overlays properties JSDoc --- interface/src/ui/overlays/Overlays.cpp | 459 ++++++++++++++----------- 1 file changed, 258 insertions(+), 201 deletions(-) diff --git a/interface/src/ui/overlays/Overlays.cpp b/interface/src/ui/overlays/Overlays.cpp index 0532b20b0f..c6bbca54e3 100644 --- a/interface/src/ui/overlays/Overlays.cpp +++ b/interface/src/ui/overlays/Overlays.cpp @@ -1336,12 +1336,12 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { * * * - * - * - * * * * + * + * + * * * * @@ -1354,10 +1354,6 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { * * - * - * - * * * @@ -1366,14 +1362,18 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { * * - * - * - * * * * + * + * + * + * + * + * * * @@ -1401,22 +1401,22 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { /**jsdoc * 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 corresponding entity properties.

+ *

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's type. Read-only. * @property {boolean} visible=true - true if the overlay is rendered, false if it isn't. * - * @see {@link Overlays.OverlayProperties-Image|OverlayProperties-Image} * @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-Cube|OverlayProperties-Cube} Deprecated. * @see {@link Overlays.OverlayProperties-Sphere|OverlayProperties-Sphere} Deprecated. - * @see {@link Overlays.OverlayProperties-Rectangle3D|OverlayProperties-Rectangle3D} Deprecated. * @see {@link Overlays.OverlayProperties-Shape|OverlayProperties-Shape} Deprecated. * @see {@link Overlays.OverlayProperties-Model|OverlayProperties-Model} Deprecated. - * @see {@link Overlays.OverlayProperties-Text3D|OverlayProperties-Text3D} 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. @@ -1430,16 +1430,16 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { * @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. */ @@ -1452,21 +1452,21 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { * @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 @@ -1478,25 +1478,25 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { * @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. * 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 @@ -1518,26 +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 parents's position and orientation rather + * than a joint. */ /**jsdoc * 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 @@ -1559,26 +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 parents's position and orientation rather + * than a joint. */ /**jsdoc * 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 @@ -1600,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 parents'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:

*
ValueDimensionsDescription
Receive "hello" messages from a web3d overlay.Receive "hello" messages from a "web3d" overlay.
Value2D/3DDescriptionProperties
"image"2DAn image.{@link Overlays.OverlayProperties-Image|OverlayProperties-Image}
"rectangle"2DA rectangle.{@link Overlays.OverlayProperties-Rectangle|OverlayProperties-Rectangle}
"image"2DAn image.{@link Overlays.OverlayProperties-Image|OverlayProperties-Image}
"text"2DSome text.{@link Overlays.OverlayProperties-Text|OverlayProperties-Text}
A sphere. A "shape" overlay can also be used to create a sphere.
* Deprecated.		{@link Overlays.OverlayProperties-Sphere|OverlayProperties-Sphere}
"rectangle3d"3DA rectangle.
- * Deprecated.		{@link Overlays.OverlayProperties-Rectangle3D|OverlayProperties-Rectangle3D}
"shape"3DA geometric shape, such as a cube, sphere, or cylinder.
* Deprecated.		A model.
* Deprecated.		{@link Overlays.OverlayProperties-Model|OverlayProperties-Model}
"text3d"3DSome text.
- * Deprecated.		{@link Overlays.OverlayProperties-Text3D|OverlayProperties-Text3D}
"image3d"3DAn image. Synonym: "billboard".
* Deprecated.		{@link Overlays.OverlayProperties-Image3D|OverlayProperties-Image3D}
"rectangle3d"3DA rectangle.
+ * Deprecated.		{@link Overlays.OverlayProperties-Rectangle3D|OverlayProperties-Rectangle3D}
"text3d"3DSome text.
+ * Deprecated.		{@link Overlays.OverlayProperties-Text3D|OverlayProperties-Text3D}
"web3d"3DWeb content.
* Deprecated.
* * @@ -1626,7 +1648,6 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { * * * - * * * * @@ -1642,11 +1663,12 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { /**jsdoc * 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 @@ -1668,15 +1690,22 @@ 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 parents's position and orientation rather + * than a joint. * * @property {Overlays.Shape} shape=Hexagon - The geometrical shape of the overlay. */ @@ -1684,6 +1713,7 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { /**jsdoc * 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. @@ -1697,44 +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 parents'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. * 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 @@ -1756,35 +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 parents's position and orientation rather + * than a joint. */ /**jsdoc * 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 @@ -1806,31 +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 parents'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 "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 @@ -1852,31 +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 parents'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 "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. @@ -1886,37 +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 parents'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 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 @@ -1938,27 +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 parents's position and orientation rather + * than a joint. */ /**jsdoc * 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 @@ -1975,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 parents'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. */ From 42bee63f52db2dafc42999c4dc2878af4be83146 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 11 Jul 2019 15:33:45 +1200 Subject: [PATCH 03/29] Update Overlays methods JSDoc --- interface/src/ui/overlays/Overlays.h | 237 ++++++++++++++++----------- 1 file changed, 139 insertions(+), 98 deletions(-) diff --git a/interface/src/ui/overlays/Overlays.h b/interface/src/ui/overlays/Overlays.h index 9ff03e0c53..41cfe13a77 100644 --- a/interface/src/ui/overlays/Overlays.h +++ b/interface/src/ui/overlays/Overlays.h @@ -71,6 +71,9 @@ public: * 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 @@ -79,9 +82,9 @@ public: * @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 { @@ -121,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. @@ -137,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 * var overlay = Overlays.addOverlay("cube", { * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })), @@ -166,12 +171,11 @@ public slots: bool editOverlay(const QUuid& id, const QVariant& properties); /**jsdoc - * Edit multiple overlays' properties. + * Edits multiple overlays' (or entities') properties. * @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 * var overlayA = Overlays.addOverlay("cube", { * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: -0.3, y: 0, z: -3 })), @@ -195,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 + * @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 * var overlay = Overlays.addOverlay("cube", { * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })), * rotation: MyAvatar.orientation, @@ -214,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 - * // HTML file: name "web3d.html". + * @example + * // 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. @@ -282,10 +312,11 @@ public slots: QUuid getOverlayAtPoint(const glm::vec2& point); /**jsdoc - * Get the value of a 3D overlay's property. + * Gets the value of a 3D overlay's (or entity's) property. + *

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 @@ -301,12 +332,13 @@ public slots: QVariant getProperty(const QUuid& id, const QString& property); /**jsdoc - * Get the values of an overlay's properties. + * Gets the values of a 3D overlay's (or entity's) properties. + *

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 * var overlay = Overlays.addOverlay("cube", { * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -3 })), @@ -320,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 * var overlayA = Overlays.addOverlay("cube", { @@ -348,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 + * @param {boolean} [precisionPicking=false] - code>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] - If true then only overlays (and local entities) that are + * {@link Overlays.OverlayProperties|visible} are searched. + * @param {boolean} [collideableOnly=false] - If true then only local 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. + * @returns {Overlays.RayToOverlayIntersectionResult} The result of the search for the first intersected overlay (or local + * entity. * @example * var overlay = Overlays.addOverlay("cube", { @@ -387,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 + * @returns {Uuid[]} The IDs of the overlays (local entities) that are visible and have bounding boxes that touch a search + * sphere. + * @example * var overlayA = Overlays.addOverlay("cube", { * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: -0.3, y: 0, z: -3 })), * rotation: MyAvatar.orientation, @@ -414,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 * var overlay = Overlays.addOverlay("image", { * bounds: { x: 100, y: 100, width: 200, height: 200 }, @@ -432,44 +465,49 @@ 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 * 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. * @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. * @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); @@ -554,18 +592,21 @@ public slots: 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); } From e1f181e8ee5d94fa22fc7542d65486c0045770cd Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 11 Jul 2019 16:15:24 +1200 Subject: [PATCH 04/29] Update Overlays events and signals JSDoc --- interface/src/ui/overlays/Overlays.h | 36 ++++++++++++++-------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/interface/src/ui/overlays/Overlays.h b/interface/src/ui/overlays/Overlays.h index 41cfe13a77..4400e39291 100644 --- a/interface/src/ui/overlays/Overlays.h +++ b/interface/src/ui/overlays/Overlays.h @@ -512,13 +512,13 @@ public slots: 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 - * var overlay = Overlays.addOverlay("cube", { + * @example + * 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 }, @@ -526,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 } * }); @@ -552,41 +552,41 @@ 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); @@ -612,9 +612,9 @@ public slots: 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 * var overlay = Overlays.addOverlay("cube", { From 46c81b268a77388ce297a4b9e9a2e488108852e1 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 11 Jul 2019 16:29:56 +1200 Subject: [PATCH 05/29] Typos and inconsistencies --- interface/src/ui/overlays/Overlays.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/interface/src/ui/overlays/Overlays.h b/interface/src/ui/overlays/Overlays.h index 4400e39291..e7308cf8b2 100644 --- a/interface/src/ui/overlays/Overlays.h +++ b/interface/src/ui/overlays/Overlays.h @@ -383,15 +383,15 @@ public slots: * 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] - code>true to pick against precise meshes, false to pick + * @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] - If true then only overlays (and local entities) that are - * {@link Overlays.OverlayProperties|visible} are searched. - * @param {boolean} [collideableOnly=false] - If true then only local entities that are not - * {@link Entities.EntityProperties|collisionless} are searched. + * @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
ValueDimensionsDescription
"Dodecahedron"3D
"Hexagon"3DA hexagonal prism.
"Icosahedron"3D
"Line"1DA line oriented in 3D.
"Octagon"3DAn octagonal prism.
"Octahedron"3D
"Quad"2DA square oriented in 3D.
Add an overlay in front of your avatar then change its color.Create two overlays in front of your avatar then change their colors.Create an object in front of your avatar then get and report its type.Create an overlay in front of your avatar then get and report its type.Receive "hello" messages from a "web3d" overlay.Exchange messages with a "web3d" overlay.Create an overlay in front of your avatar then report its alpha property value.Create an overlay in front of your avatar then report some of its properties.Create two cube overlays in front of your avatar then get some of their properties.Create a cube overlay in front of your avatar. Report 3D overlay intersection details for mouse * clicks.Create two cube entities in front of your avatar then search for entities near your avatar.Create two overlays in front of your avatar then search for overlays near your avatar.Create an image overlay and report whether its image is loaded after 1s.Calculate the size of "hello" in a 3D text entity.Create a 2D rectangle overlay plus a 3D cube overlay and generate mousePressOnOverlay events for the 2D - * overlay.Create a 2D rectangle overlay plus a 3D cube overlay and generate mousePressOnOverlay events for the + * 2D overlay.Create an overlay then delete it after 1s.Create a cube overlay in front of your avatar. Report 3D overlay intersection details for mouse From a45d8924fa5e40b7273e376d6ea2164671eb7733 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 11 Jul 2019 16:31:09 +1200 Subject: [PATCH 06/29] Miscellaneous minor JSDoc fixes noticed in passing --- .../src/raypick/PickScriptingInterface.h | 4 ++-- .../src/raypick/RayPickScriptingInterface.h | 4 ++-- interface/src/scripting/Audio.h | 2 +- .../src/scripting/HMDScriptingInterface.h | 2 +- .../src/scripting/WindowScriptingInterface.h | 2 +- .../entities/src/EntityItemProperties.cpp | 4 ++-- .../entities/src/EntityScriptingInterface.h | 23 ++++++++++++++----- libraries/entities/src/ShapeEntityItem.cpp | 2 +- libraries/pointers/src/Pick.h | 2 +- libraries/shared/src/PickFilter.h | 2 +- libraries/shared/src/RenderLayer.h | 4 ++-- 11 files changed, 31 insertions(+), 20 deletions(-) diff --git a/interface/src/raypick/PickScriptingInterface.h b/interface/src/raypick/PickScriptingInterface.h index 1cbdaa92f7..d8654e2a13 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 32a2ec4a5d..41972ca52d 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 335816bf7c..0f636a388b 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..b5b7f3c8b9 100644 --- a/interface/src/scripting/WindowScriptingInterface.h +++ b/interface/src/scripting/WindowScriptingInterface.h @@ -666,7 +666,7 @@ 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 + * @param {boolean} interstitialMode - The new interstitial mode value. If true, the interstitial graphics are * displayed when the domain is loading. * @returns {Signal} */ diff --git a/libraries/entities/src/EntityItemProperties.cpp b/libraries/entities/src/EntityItemProperties.cpp index 064fe2e3b1..003985bfa3 100644 --- a/libraries/entities/src/EntityItemProperties.cpp +++ b/libraries/entities/src/EntityItemProperties.cpp @@ -987,8 +987,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

*