From c70d2c006f546b652050d76bb5e78b8b3549979a Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 3 Jul 2019 14:25:11 +1200 Subject: [PATCH] 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". * *
ValueDimensionsDescription
Receive "hello" messages from a web3d overlay.Receive "hello" messages from a "web3d" overlay.