From f2cf3bd05c37518f758c29dde3e4f3f2dfb34ffc Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 2 Jul 2019 08:10:36 +1200 Subject: [PATCH 1/6] Revise Pointers API JSDoc --- .../src/raypick/PointerScriptingInterface.cpp | 250 ++++++----- .../src/raypick/PointerScriptingInterface.h | 397 ++++++++++++++---- 2 files changed, 467 insertions(+), 180 deletions(-) diff --git a/interface/src/raypick/PointerScriptingInterface.cpp b/interface/src/raypick/PointerScriptingInterface.cpp index 1c80caff88..d904706b08 100644 --- a/interface/src/raypick/PointerScriptingInterface.cpp +++ b/interface/src/raypick/PointerScriptingInterface.cpp @@ -51,21 +51,21 @@ unsigned int PointerScriptingInterface::createPointer(const PickQuery::PickType& } /**jsdoc - * A set of properties that can be passed to {@link Pointers.createPointer} to create a new Pointer. Contains the relevant {@link Picks.PickProperties} to define the underlying Pick. + * The properties of a stylus pointer. These include the properties from the underlying stylus pick that the pointer uses. * @typedef {object} Pointers.StylusPointerProperties - * @property {boolean} [hover=false] If this pointer should generate hover events. - * @property {boolean} [enabled=false] - * @property {Vec3} [tipOffset] The specified offset of the from the joint index. - * @property {Pointers.StylusPointerProperties.model} [model] Data to replace the default model url, positionOffset and rotationOffset. + * @property {Pointers.StylusPointerModel} [model] - Override some or all of the default stylus model properties. + * @property {boolean} [hover=false] - If true, the pointer generates {@link Entities} hover events. + * @see {@link Picks.StylusPickProperties} for additional properties from the underlying stylus pick. + */ +/**jsdoc + * The properties of a stylus pointer model. + * @typedef {object} Pointers.StylusPointerModel + * @property {string} [url] - The url of a model to use for the stylus, to override the default stylus mode. + * @property {Vec3} [dimensions] - The dimensions of the stylus, to override the default stylus dimensions. + * @property {Vec3} [positionOffset] - The position offset of the model from the stylus tip, to override the default position + * offset. + * @property {Quat} [rotationOffset] - The rotation offset of the model from the hand, to override the default rotation offset. */ - /**jsdoc - * properties defining stylus pick model that can be included to {@link Pointers.StylusPointerProperties} - * @typedef {object} Pointers.StylusPointerProperties.model - * @property {string} [url] url to the model - * @property {Vec3} [dimensions] the dimensions of the model - * @property {Vec3} [positionOffset] the position offset of the model from the stylus tip. - * @property {Vec3} [rotationOffset] the rotation offset of the model from the parent joint index - */ unsigned int PointerScriptingInterface::createStylus(const QVariant& properties) const { QVariantMap propertyMap = properties.toMap(); @@ -104,48 +104,76 @@ unsigned int PointerScriptingInterface::createStylus(const QVariant& properties) } /**jsdoc - * A set of properties used to define the visual aspect of a Ray Pointer in the case that the Pointer is not intersecting something. Same as a {@link Pointers.RayPointerRenderState}, - * but with an additional distance field. - * + * Properties that define the visual appearance of a ray pointer when the pointer is not intersecting something. These are the + * properties of {@link Pointers.RayPointerRenderState} but with an additional property. * @typedef {object} Pointers.DefaultRayPointerRenderState - * @augments Pointers.RayPointerRenderState - * @property {number} distance The distance at which to render the end of this Ray Pointer, if one is defined. + * @property {number} distance - The distance at which to render the end of the ray pointer. + * @see {@link Pointers.RayPointerRenderState} for the remainder of the properties. */ /**jsdoc - * A set of properties which define the visual aspect of a Ray Pointer in the case that the Pointer is intersecting something. - * + * Properties that define the visual appearance of a ray pointer when the pointer is intersecting something. * @typedef {object} Pointers.RayPointerRenderState - * @property {string} name When using {@link Pointers.createPointer}, the name of this render state, used by {@link Pointers.setRenderState} and {@link Pointers.editRenderState} - * @property {Overlays.OverlayProperties|QUuid} [start] When using {@link Pointers.createPointer}, an optionally defined object to represent the beginning of the Ray Pointer, - * using the properties you would normally pass to {@link Overlays.addOverlay}, plus the type (as a type field). - * When returned from {@link Pointers.getPointerProperties}, the ID of the created object if it exists, or a null ID otherwise. - * @property {Overlays.OverlayProperties|QUuid} [path] When using {@link Pointers.createPointer}, an optionally defined object to represent the path of the Ray Pointer, - * using the properties you would normally pass to {@link Overlays.addOverlay}, plus the type (as a type field), which must be "line3d". - * When returned from {@link Pointers.getPointerProperties}, the ID of the created object if it exists, or a null ID otherwise. - * @property {Overlays.OverlayProperties|QUuid} [end] When using {@link Pointers.createPointer}, an optionally defined object to represent the end of the Ray Pointer, - * using the properties you would normally pass to {@link Overlays.addOverlay}, plus the type (as a type field). - * When returned from {@link Pointers.getPointerProperties}, the ID of the created object if it exists, or a null ID otherwise. + * @property {string} name - When creating using {@link Pointers.createPointer}, the name of the render state. + * @property {Overlays.OverlayProperties|Uuid} [start] + *

When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of + * an overlay to render at the start of the ray pointer. The type property must be specified.

+ *

When getting using {@link Pointers.getPointerProperties}, the ID of the overlay rendered at the start of the ray; + * null if there is no overlay. + * + * @property {Overlays.OverlayProperties|Uuid} [path] + *

When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of + * the overlay rendered for the path of the ray pointer. The type property must be specified and be + * "line3d".

+ *

When getting using {@link Pointers.getPointerProperties}, the ID of the overlay rendered for the path of the ray; + * null if there is no overlay. + * + * @property {Overlays.OverlayProperties|Uuid} [end] + *

When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of + * an overlay to render at the end of the ray pointer. The type property must be specified.

+ *

When getting using {@link Pointers.getPointerProperties}, the ID of the overlay rendered at the end of the ray; + * null if there is no overlay. */ /**jsdoc - * A set of properties that can be passed to {@link Pointers.createPointer} to create a new Pointer. Contains the relevant {@link Picks.PickProperties} to define the underlying Pick. - * @typedef {object} Pointers.LaserPointerProperties - * @property {boolean} [faceAvatar=false] If true, the end of the Pointer will always rotate to face the avatar. - * @property {boolean} [centerEndY=true] If false, the end of the Pointer will be moved up by half of its height. - * @property {boolean} [lockEnd=false] If true, the end of the Pointer will lock on to the center of the object at which the pointer is pointing. - * @property {boolean} [distanceScaleEnd=false] If true, the dimensions of the end of the Pointer will scale linearly with distance. - * @property {boolean} [scaleWithParent=false] If true, the width of the Pointer's path will scale linearly with the pick parent's scale. scaleWithAvatar is an alias but is deprecated. - * @property {boolean} [followNormal=false] If true, the end of the Pointer will rotate to follow the normal of the intersected surface. - * @property {number} [followNormalStrength=0.0] The strength of the interpolation between the real normal and the visual normal if followNormal is true. 0-1. If 0 or 1, - * the normal will follow exactly. - * @property {boolean} [enabled=false] - * @property {Pointers.RayPointerRenderState[]|Object.} [renderStates] A collection of different visual states to switch between. - * When using {@link Pointers.createPointer}, a list of RayPointerRenderStates. - * When returned from {@link Pointers.getPointerProperties}, a map between render state names and RayPointRenderStates. - * @property {Pointers.DefaultRayPointerRenderState[]|Object.} [defaultRenderStates] A collection of different visual states to use if there is no intersection. - * When using {@link Pointers.createPointer}, a list of DefaultRayPointerRenderStates. - * When returned from {@link Pointers.getPointerProperties}, a map between render state names and DefaultRayPointRenderStates. - * @property {boolean} [hover=false] If this Pointer should generate hover events. - * @property {Pointers.Trigger[]} [triggers] A list of different triggers mechanisms that control this Pointer's click event generation. + * The properties of a ray pointer. These include the properties from the underlying ray pick that the pointer uses. + * @typedef {object} Pointers.RayPointerProperties + * @property {boolean} [faceAvatar=false] - true if the overlay rendered at the end of the ray rotates about the + * world y-axis to always face the avatar; false if it maintains its world orientation. + * @property {boolean} [centerEndY=true] - true if the overlay rendered at the end of the ray is centered on + * the ray end; false if the overlay is rendered adjacent to the surface if followNormal is + * true or on top of the ray end if if followNormal is false. +* @property {boolean} [lockEnd=false] - true if the end of the ray is locked to the center of the object at + * which the ray is pointing; false if the end of the ray is at the intersected surface. + * @property {boolean} [distanceScaleEnd=false] - true if the dimensions of the overlay at the end of the ray + * scale linearly with distance; false if they aren't. + * @property {boolean} [scaleWithParent=false] - true if the width of the ray's path and the size of the + * start and end overlays scale linearly with the pointer parent's scale; false if they don't scale. + * @property {boolean} [scaleWithAvatar=false] - A synonym for scalewithParent. + *

Deprecated: This property is deprecated and will be removed.

+ * @property {boolean} [followNormal=false] - true if the overlay rendered at the end of the ray rotates to + * follow the normal of the surface if one is intersected; false if it doesn't. + * @property {number} [followNormalStrength=0.0] - How quickly the overlay rendered at the end of the ray rotates to follow + * the normal of an intersected surface. If 0 or 1, the overlay rotation follows instantaneously; + * for other values, the larger the value the more quickly the rotation follows. + * @property {Pointers.RayPointerRenderState[]|Object.} [renderStates] + *

A set of visual states that can be switched among using {@link Pointers.setRenderState}. These define the visual + * appearance of the pointer when it is intersecting something.

+ *

When setting using {@link Pointers.createPointer}, an array of + * {@link Pointers.RayPointerRenderState|RayPointerRenderState} values.

+ *

When getting using {@link Pointers.getPointerProperties}, an object mapping render state names to + * {@link Pointers.RayPointerRenderState|RayPointerRenderState} values.

+ * @property {Pointers.DefaultRayPointerRenderState[]|Object.} + * [defaultRenderStates] + *

A set of visual states that can be switched among using {@link Pointers.setRenderState}. These define the visual + * appearance of the pointer when it is not intersecting something.

+ *

When setting using {@link Pointers.createPointer}, an array of + * {@link Pointers.DefaultRayPointerRenderState|DefaultRayPointerRenderState} values.

+ *

When getting using {@link Pointers.getPointerProperties}, an object mapping render state names to + * {@link Pointers.DefaultRayPointerRenderState|DefaultRayPointerRenderState} values.

+ * @property {boolean} [hover=false] - true if the pointer generates {@link Entities} hover events, + * false if it doesn't. + * @property {Pointers.Trigger[]} [triggers=[]] - A list of ways that a {@link Controller} action or function should trigger + * events on the entity or overlay currently intersected. + * @see {@link Picks.RayPickProperties} for additional properties from the underlying ray pick. */ unsigned int PointerScriptingInterface::createLaserPointer(const QVariant& properties) const { QVariantMap propertyMap = properties.toMap(); @@ -260,58 +288,84 @@ unsigned int PointerScriptingInterface::createLaserPointer(const QVariant& prope } /**jsdoc -* The rendering properties of the parabolic path -* -* @typedef {object} Pointers.ParabolaProperties -* @property {Color} color=255,255,255 The color of the parabola. -* @property {number} alpha=1.0 The alpha of the parabola. -* @property {number} width=0.01 The width of the parabola, in meters. -* @property {boolean} isVisibleInSecondaryCamera=false The width of the parabola, in meters. -* @property {boolean} drawInFront=false If true, the parabola is rendered in front of other items in the scene. -*/ + * The visual appearance of the parabolic path. + * @typedef {object} Pointers.ParabolaPointerPath + * @property {Color} [color=255,255,255] - The color of the parabola. + * @property {number} [alpha=1.0] - The opacity of the parabola, range 0.0 – 1.0. + * @property {number} [width=0.01] - The width of the parabola, in meters. + * @property {boolean} [isVisibleInSecondaryCamera=false] - true if the parabola is rendered in the secondary + * camera, false if it isn't. + * @property {boolean} [drawInFront=false] - true if the parabola is rendered in front of objects in the world, + * but behind the HUD, false if it is occluded by objects in front of it. + */ /**jsdoc -* A set of properties used to define the visual aspect of a Parabola Pointer in the case that the Pointer is not intersecting something. Same as a {@link Pointers.ParabolaPointerRenderState}, -* but with an additional distance field. -* -* @typedef {object} Pointers.DefaultParabolaPointerRenderState -* @augments Pointers.ParabolaPointerRenderState -* @property {number} distance The distance along the parabola at which to render the end of this Parabola Pointer, if one is defined. -*/ + * Properties that define the visual appearance of a parabola pointer when the pointer is not intersecting something. These are + * properties of {@link Pointers.ParabolaPointerRenderState} but with an additional property. + * @typedef {object} Pointers.DefaultParabolaPointerRenderState + * @property {number} distance - The distance along the parabola at which to render the end of the parabola pointer. + * @see {@link Pointers.ParabolaPointerRenderState} for the remainder of the properties. + */ /**jsdoc -* A set of properties used to define the visual aspect of a Parabola Pointer in the case that the Pointer is intersecting something. -* -* @typedef {object} Pointers.ParabolaPointerRenderState -* @property {string} name When using {@link Pointers.createPointer}, the name of this render state, used by {@link Pointers.setRenderState} and {@link Pointers.editRenderState} -* @property {Overlays.OverlayProperties|QUuid} [start] When using {@link Pointers.createPointer}, an optionally defined object to represent the beginning of the Parabola Pointer, -* using the properties you would normally pass to {@link Overlays.addOverlay}, plus the type (as a type field). -* When returned from {@link Pointers.getPointerProperties}, the ID of the created object if it exists, or a null ID otherwise. -* @property {Pointers.ParabolaProperties} [path] When using {@link Pointers.createPointer}, the optionally defined rendering properties of the parabolic path defined by the Parabola Pointer. -* Not defined in {@link Pointers.getPointerProperties}. -* @property {Overlays.OverlayProperties|QUuid} [end] When using {@link Pointers.createPointer}, an optionally defined object to represent the end of the Parabola Pointer, -* using the properties you would normally pass to {@link Overlays.addOverlay}, plus the type (as a type field). -* When returned from {@link Pointers.getPointerProperties}, the ID of the created object if it exists, or a null ID otherwise. -*/ + * Properties that define the visual appearance of a parabola pointer when the pointer is intersecting something. + * @typedef {object} Pointers.ParabolaPointerRenderState + * @property {string} name - When creating using {@link Pointers.createPointer}, the name of the render state. + * @property {Overlays.OverlayProperties|Uuid} [start] + *

When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of + * an overlay to render at the start of the parabola pointer. The type property must be specified.

+ *

When getting using {@link Pointers.getPointerProperties}, the ID of the overlay rendered at the start of the + * parabola; null if there is no overlay. + * @property {Pointers.ParabolaPointerPath|Uuid} [path] + *

When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of + * the rendered path of the parabola pointer.

+ *

This property is not provided when getting using {@link Pointers.getPointerProperties}. + * @property {Overlays.OverlayProperties|Uuid} [end] + *

When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of + * an overlay to render at the end of the ray pointer. The type property must be specified.

+ *

When getting using {@link Pointers.getPointerProperties}, the ID of the overlay rendered at the end of the parabola; + * null if there is no overlay. + */ /**jsdoc -* A set of properties that can be passed to {@link Pointers.createPointer} to create a new Pointer. Contains the relevant {@link Picks.PickProperties} to define the underlying Pick. -* @typedef {object} Pointers.ParabolaPointerProperties -* @property {boolean} [faceAvatar=false] If true, the end of the Pointer will always rotate to face the avatar. -* @property {boolean} [centerEndY=true] If false, the end of the Pointer will be moved up by half of its height. -* @property {boolean} [lockEnd=false] If true, the end of the Pointer will lock on to the center of the object at which the pointer is pointing. -* @property {boolean} [distanceScaleEnd=false] If true, the dimensions of the end of the Pointer will scale linearly with distance. -* @property {boolean} [scaleWithParent=true] If true, the width of the Pointer's path will scale linearly with the pick parent's scale. scaleWithAvatar is an alias but is deprecated. -* @property {boolean} [followNormal=false] If true, the end of the Pointer will rotate to follow the normal of the intersected surface. -* @property {number} [followNormalStrength=0.0] The strength of the interpolation between the real normal and the visual normal if followNormal is true. 0-1. If 0 or 1, -* the normal will follow exactly. -* @property {boolean} [enabled=false] -* @property {Pointers.ParabolaPointerRenderState[]|Object.} [renderStates] A collection of different visual states to switch between. -* When using {@link Pointers.createPointer}, a list of ParabolaPointerRenderStates. -* When returned from {@link Pointers.getPointerProperties}, a map between render state names and ParabolaPointerRenderStates. -* @property {Pointers.DefaultParabolaPointerRenderState[]|Object.} [defaultRenderStates] A collection of different visual states to use if there is no intersection. -* When using {@link Pointers.createPointer}, a list of DefaultParabolaPointerRenderStates. -* When returned from {@link Pointers.getPointerProperties}, a map between render state names and DefaultParabolaPointerRenderStates. -* @property {boolean} [hover=false] If this Pointer should generate hover events. -* @property {Pointers.Trigger[]} [triggers] A list of different triggers mechanisms that control this Pointer's click event generation. -*/ + * The properties of a parabola pointer. These include the properties from the underlying parabola pick that the pointer uses. + * @typedef {object} Pointers.ParabolaPointerProperties + * @property {boolean} [faceAvatar=false] - true if the overlay rendered at the end of the ray rotates about the + * world y-axis to always face the avatar; false if it maintains its world orientation. + * @property {boolean} [centerEndY=true] - true if the overlay rendered at the end of the ray is centered on + * the ray end; false if the overlay is rendered adjacent to the surface if followNormal is + * true or on top of the ray end if if followNormal is false. +* @property {boolean} [lockEnd=false] - true if the end of the ray is locked to the center of the object at + * which the ray is pointing; false if the end of the ray is at the intersected surface. + * @property {boolean} [distanceScaleEnd=false] - true if the dimensions of the overlay at the end of the ray + * scale linearly with distance; false if they aren't. + * @property {boolean} [scaleWithParent=false] - true if the width of the ray's path and the size of the + * start and end overlays scale linearly with the pointer parent's scale; false if they don't scale. + * @property {boolean} [scaleWithAvatar=false] - A synonym for scalewithParent. + *

Deprecated: This property is deprecated and will be removed.

+ * @property {boolean} [followNormal=false] - true if the overlay rendered at the end of the ray rotates to + * follow the normal of the surface if one is intersected; false if it doesn't. + * @property {number} [followNormalStrength=0.0] - How quickly the overlay rendered at the end of the ray rotates to follow + * the normal of an intersected surface. If 0 or 1, the overlay rotation follows instantaneously; + * for other values, the larger the value the more quickly the rotation follows. + * @property {Pointers.ParabolaPointerRenderState[]|Object.} [renderStates] + *

A set of visual states that can be switched among using {@link Pointers.setRenderState}. These define the visual + * appearance of the pointer when it is intersecting something.

+ *

When setting using {@link Pointers.createPointer}, an array of + * {@link Pointers.ParabolaPointerRenderState|ParabolaPointerRenderState} values.

+ *

When getting using {@link Pointers.getPointerProperties}, an object mapping render state names to + * {@link Pointers.ParabolaPointerRenderState|ParabolaPointerRenderState} values.

+ * @property {Pointers.DefaultParabolaPointerRenderState[]|Object.} + * [defaultRenderStates] + *

A set of visual states that can be switched among using {@link Pointers.setRenderState}. These define the visual + * appearance of the pointer when it is not intersecting something.

+ *

When setting using {@link Pointers.createPointer}, an array of + * {@link Pointers.DefaultParabolaPointerRenderState|DefaultParabolaPointerRenderState} values.

+ *

When getting using {@link Pointers.getPointerProperties}, an object mapping render state names to + * {@link Pointers.DefaultParabolaPointerRenderState|DefaultParabolaPointerRenderState} values.

+ * @property {boolean} [hover=false] - true if the pointer generates {@link Entities} hover events, + * false if it doesn't. + * @property {Pointers.Trigger[]} [triggers=[]] - A list of ways that a {@link Controller} action or function should trigger + * events on the entity or overlay currently intersected. + * @see {@link Picks.ParabolaPickProperties} for additional properties from the underlying parabola pick. + */ unsigned int PointerScriptingInterface::createParabolaPointer(const QVariant& properties) const { QVariantMap propertyMap = properties.toMap(); diff --git a/interface/src/raypick/PointerScriptingInterface.h b/interface/src/raypick/PointerScriptingInterface.h index 268b178fb6..58959570ab 100644 --- a/interface/src/raypick/PointerScriptingInterface.h +++ b/interface/src/raypick/PointerScriptingInterface.h @@ -15,8 +15,9 @@ #include /**jsdoc - * The Pointers API lets you create and manage objects for repeatedly calculating intersections in different ways, as well as the visual representation of those objects. - * Pointers can also be configured to automatically generate {@link PointerEvent}s on {@link Entities}. + * The Pointers API lets you create, manage, and visually represent objects for repeatedly calculating + * intersections with avatars, entities, and overlays. Pointers can also be configured to generate events on entities and + * overlays intersected. * * @namespace Pointers * @@ -35,184 +36,416 @@ public: unsigned int createParabolaPointer(const QVariant& properties) const; /**jsdoc - * A trigger mechanism for Ray and Parabola Pointers. - * - * @typedef {object} Pointers.Trigger - * @property {Controller.Standard|Controller.Actions|function} action This can be a built-in Controller action, like Controller.Standard.LTClick, or a function that evaluates to >= 1.0 when you want to trigger button. - * @property {string} button Which button to trigger. "Primary", "Secondary", "Tertiary", and "Focus" are currently supported. Only "Primary" will trigger clicks on web surfaces. If "Focus" is triggered, - * it will try to set the entity focus to the object at which the Pointer is aimed. Buttons besides the first three will still trigger events, but event.button will be "None". - */ + * Specifies that a {@link Controller} action or function should trigger events on the entity or overlay currently + * intersected by a {@link Pointers.RayPointerProperties|Ray} or {@link Pointers.ParabolaPointerProperties|Parabola} + * pointer. + * @typedef {object} Pointers.Trigger + * @property {Controller.Standard|Controller.Actions|function} action - The controller output or function that triggers the + * events on the entity or overlay. If a function, it must return a number >= 1.0 to start the action and + * < 1.0 to terminate the action. + * @property {string} button - Which button to trigger. + *
    + *
  • "Primary", "Secondary", and "Tertiary" cause {@link Entities} and + * {@link Overlays} mouse pointer events. Other button names also cause mouse events but the button + * property in the event will be "None".
    • + *
  • "Focus" will try to give focus to the entity or overlay which the pointer is intersecting.
    • + *
+ */ /**jsdoc - * Adds a new Pointer - * Different {@link PickType}s use different properties, and within one PickType, the properties you choose can lead to a wide range of behaviors. For example, - * with PickType.Ray, depending on which optional parameters you pass, you could create a Static Ray Pointer, a Mouse Ray Pointer, or a Joint Ray Pointer. - * Pointers created with this method always intersect at least visible and collidable things + * Creates a new ray, parabola, or stylus pointer. The pointers can have a wide range of behaviors depending on the + * properties specified. For example, a ray pointer may be a static ray pointer, a mouse ray pointer, or joint ray + * pointer. + *

Warning: Pointers created using this method currently always intersect at least visible and + * collidable things but this may not always be the case.

* @function Pointers.createPointer - * @param {PickType} type A PickType that specifies the method of picking to use. Cannot be {@link PickType|PickType.Collision}. - * @param {Pointers.LaserPointerProperties|Pointers.StylusPointerProperties|Pointers.ParabolaPointerProperties} properties A PointerProperties object, containing all the properties for initializing this Pointer and the {@link Picks.PickProperties} for the Pick that - * this Pointer will use to do its picking. - * @returns {number} The ID of the created Pointer. Used for managing the Pointer. 0 if invalid. + * @param {PickType} type - The type of pointer to create. Cannot be {@link PickType|PickType.Collision}. + * @param {Pointers.RayPointerProperties|Pointers.ParabolaPointerProperties|Pointers.StylusPointerProperties} properties - + * The properties of the pointer, per the pointer type, including the properties of the underlying pick + * that the pointer uses to do its picking. + * @returns {number} The ID of the pointer if successfully created, otherwise 0. * - * @example Create a left hand Ray Pointer that triggers events on left controller trigger click and changes color when it's intersecting something. - * - * var end = { + * @example Create a ray pointer on the left hand that changes color when it's intersecting and that triggers + * events.
+ * Note: Stop controllerScripts.js from running to disable similar behavior from it. + * var intersectEnd = { * type: "sphere", - * dimensions: {x:0.5, y:0.5, z:0.5}, + * dimensions: { x: 0.2, y: 0.2, z: 0.2 }, * solid: true, - * color: {red:0, green:255, blue:0}, + * color: { red: 0, green: 255, blue: 0 }, * ignorePickIntersection: true * }; - * var end2 = { + * var intersectedPath = { + * type: "line3d", + * color: { red: 0, green: 255, blue: 0 }, + * }; + * var searchEnd = { * type: "sphere", - * dimensions: {x:0.5, y:0.5, z:0.5}, + * dimensions: { x: 0.2, y: 0.2, z: 0.2 }, * solid: true, - * color: {red:255, green:0, blue:0}, + * color: { red: 255, green: 0, blue: 0 }, * ignorePickIntersection: true * }; - * - * var renderStates = [ {name: "test", end: end} ]; - * var defaultRenderStates = [ {name: "test", distance: 10.0, end: end2} ]; - * var pointer = Pointers.createPointer(PickType.Ray, { + * var searchPath = { + * type: "line3d", + * color: { red: 255, green: 0, blue: 0 }, + * }; + * + * var renderStates = [{ name: "example", path: intersectedPath, end: intersectEnd }]; + * var defaultRenderStates = [{ name: "example", distance: 20.0, path: searchPath, end: searchEnd }]; + * + * // Create the pointer. + * var rayPointer = Pointers.createPointer(PickType.Ray, { * joint: "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", * filter: Picks.PICK_LOCAL_ENTITIES | Picks.PICK_DOMAIN_ENTITIES | Picks.PICK_INCLUDE_NONCOLLIDABLE, * renderStates: renderStates, * defaultRenderStates: defaultRenderStates, - * distanceScaleEnd: true, - * triggers: [ {action: Controller.Standard.LTClick, button: "Focus"}, {action: Controller.Standard.LTClick, button: "Primary"} ], - * hover: true, + * hover: true, // Generate hover events. + * triggers: [ + * { action: Controller.Standard.LTClick, button: "Primary" }, // Generate mouse events. + * { action: Controller.Standard.LTClick, button: "Focus" } // Focus on web entities. + * ], * enabled: true * }); - * Pointers.setRenderState(pointer, "test"); + * Pointers.setRenderState(rayPointer, "example"); + * + * // Hover events. + * Entities.hoverEnterEntity.connect(function (entityID, event) { + * print("hoverEnterEntity() : " + entityID); + * }); + * Entities.hoverLeaveEntity.connect(function (entityID, event) { + * print("hoverLeaveEntity() : " + entityID); + * }); + * + * // Mouse events. + * Entities.mousePressOnEntity.connect(function (entityID, event) { + * print("mousePressOnEntity() : " + entityID + " , " + event.button); + * }); + * Entities.mouseReleaseOnEntity.connect(function (entityID, event) { + * print("mouseReleaseOnEntity() : " + entityID + " , " + event.button); + * }); + * + * // Tidy up. + * Script.scriptEnding.connect(function () { + * Pointers.removePointer(rayPointer); + * }); */ // TODO: expand Pointers to be able to be fully configurable with PickFilters Q_INVOKABLE unsigned int createPointer(const PickQuery::PickType& type, const QVariant& properties); /**jsdoc - * Enables a Pointer. + * Enables and shows a pointer. Enabled pointers update their pick results and generate events. * @function Pointers.enablePointer - * @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}. + * @param {number} id - The ID of the pointer. */ Q_INVOKABLE void enablePointer(unsigned int uid) const { DependencyManager::get()->enablePointer(uid); } /**jsdoc - * Disables a Pointer. + * Disables and hides a pointer. Disabled pointers do not update their pick results or generate events. * @function Pointers.disablePointer - * @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}. + * @param {number} id - The ID of the pointer. */ Q_INVOKABLE void disablePointer(unsigned int uid) const { DependencyManager::get()->disablePointer(uid); } /**jsdoc - * Removes a Pointer. + * Removes (deletes) a pointer. * @function Pointers.removePointer - * @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}. + * @param {number} id - The ID of the pointer. */ Q_INVOKABLE void removePointer(unsigned int uid) const { DependencyManager::get()->removePointer(uid); } /**jsdoc - * Edit some visual aspect of a Pointer. Currently only supported for Ray Pointers. + * Edits a render state of a {@link Pointers.RayPointerProperties|ray} or + * {@link Pointers.ParabolaPointerProperties|parabola} pointer, to change its visual appearance for the state when the + * pointer is intersecting something. + *

Note: You can only edit the properties of the existing parts of the pointer; you cannot change the + * type of any part.

+ *

Note: You cannot use this method to change the appearance of a default render state.

+ *

Note: Not able to be used with stylus pointers.

* @function Pointers.editRenderState - * @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}. - * @param {string} renderState The name of the render state you want to edit. - * @param {Pointers.RayPointerRenderState} properties The new properties for renderStates item. + * @param {number} id - The ID of the pointer. + * @param {string} renderState - The name of the render state to edit. + * @param {Pointers.RayPointerRenderState|Pointers.ParabolaPointerRenderState} properties - The new properties for the + * render state. Only the overlay properties to change need be specified. + * @example Change the dimensions of a ray pointer's intersecting end overlay. + * var intersectEnd = { + * type: "sphere", + * dimensions: { x: 0.2, y: 0.2, z: 0.2 }, + * solid: true, + * color: { red: 0, green: 255, blue: 0 }, + * ignorePickIntersection: true + * }; + * var intersectedPath = { + * type: "line3d", + * color: { red: 0, green: 255, blue: 0 }, + * }; + * var searchEnd = { + * type: "sphere", + * dimensions: { x: 0.2, y: 0.2, z: 0.2 }, + * solid: true, + * color: { red: 255, green: 0, blue: 0 }, + * ignorePickIntersection: true + * }; + * var searchPath = { + * type: "line3d", + * color: { red: 255, green: 0, blue: 0 }, + * }; + * + * var renderStates = [ { name: "example", path: intersectedPath, end: intersectEnd } ]; + * var defaultRenderStates = [ { name: "example", distance: 20.0, path: searchPath, end: searchEnd } ]; + * + * // Create the pointer. + * var rayPointer = Pointers.createPointer(PickType.Ray, { + * joint: "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", + * filter: Picks.PICK_LOCAL_ENTITIES | Picks.PICK_DOMAIN_ENTITIES | Picks.PICK_INCLUDE_NONCOLLIDABLE, + * renderStates: renderStates, + * defaultRenderStates: defaultRenderStates, + * enabled: true + * }); + * Pointers.setRenderState(rayPointer, "example"); + * + * // Edit the intersecting render state. + * Script.setTimeout(function () { + * print("Edit render state"); + * Pointers.editRenderState(rayPointer, "example", { + * end: { dimensions: { x: 0.5, y: 0.5, z: 0.5 } } + * }); + * }, 10000); + * + * Script.setTimeout(function () { + * print("Edit render state"); + * Pointers.editRenderState(rayPointer, "example", { + * end: { dimensions: { x: 0.2, y: 0.2, z: 0.2 } } + * }); + * }, 15000); + * + * // Tidy up. + * Script.scriptEnding.connect(function () { + * Pointers.removePointer(rayPointer); + * }); */ Q_INVOKABLE void editRenderState(unsigned int uid, const QString& renderState, const QVariant& properties) const; /**jsdoc - * Set the render state of a Pointer. For Ray Pointers, this means switching between their {@link Pointers.RayPointerRenderState}s, or "" to turn off rendering and hover/trigger events. - * For Stylus Pointers, there are three built-in options: "events on" (render and send events, the default), "events off" (render but don't send events), and "disabled" (don't render, don't send events). + * Sets the render state of a pointer, to change its visual appearance and possibly disable or enable it. * @function Pointers.setRenderState - * @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}. - * @param {string} renderState The name of the render state to which you want to switch. + * @param {number} id - The ID of the pointer. + * @param {string} renderState -

The name of the render state to set the pointer to.

+ *

For {@link Pointers.RayPointerProperties|ray} and {@link Pointers.ParabolaPointerProperties|parabola} pointers, + * this may be:

+ *
    + *
  • The name of one of the render states set in the pointer's properties.
    • + *
  • "", to hide the pointer and disable emitting of events.
    • + *
+ *

For {@link Pointers.StylusPointerProperties|stylus} pointers, the values may be:

+ *
    + *
  • "events on", to render and emit events (the default).
    • + *
  • "events off", to render but don't emit events.
    • + *
  • "disabled", to not render and not emit events.
    • + *
+ * @example Switch a ray pointer between having a path and not having a path. + * var intersectEnd = { + * type: "sphere", + * dimensions: { x: 0.2, y: 0.2, z: 0.2 }, + * solid: true, + * color: { red: 0, green: 255, blue: 0 }, + * ignorePickIntersection: true + * }; + * var intersectedPath = { + * type: "line3d", + * color: { red: 0, green: 255, blue: 0 }, + * }; + * var searchEnd = { + * type: "sphere", + * dimensions: { x: 0.2, y: 0.2, z: 0.2 }, + * solid: true, + * color: { red: 255, green: 0, blue: 0 }, + * ignorePickIntersection: true + * }; + * var searchPath = { + * type: "line3d", + * color: { red: 255, green: 0, blue: 0 }, + * }; + * + * var renderStates = [ + * { name: "examplePath", path: intersectedPath, end: intersectEnd }, + * { name: "exampleNoPath", end: intersectEnd } + * ]; + * var defaultRenderStates = [ + * { name: "examplePath", distance: 20.0, path: searchPath, end: searchEnd }, + * { name: "exampleNoPath", distance: 20.0, end: searchEnd } + * ]; + * + * // Create the pointer. + * var rayPointer = Pointers.createPointer(PickType.Ray, { + * joint: "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", + * filter: Picks.PICK_LOCAL_ENTITIES | Picks.PICK_DOMAIN_ENTITIES | Picks.PICK_INCLUDE_NONCOLLIDABLE, + * renderStates: renderStates, + * defaultRenderStates: defaultRenderStates, + * enabled: true + * }); + * Pointers.setRenderState(rayPointer, "examplePath"); + * + * // Change states. + * Script.setTimeout(function () { + * print("Without path"); + * Pointers.setRenderState(rayPointer, "exampleNoPath"); + * }, 10000); + * + * Script.setTimeout(function () { + * print("With path"); + * Pointers.setRenderState(rayPointer, "examplePath"); + * }, 15000); + * + * // Tidy up. + * Script.scriptEnding.connect(function () { + * Pointers.removePointer(rayPointer); + * }); */ Q_INVOKABLE void setRenderState(unsigned int uid, const QString& renderState) const { DependencyManager::get()->setRenderState(uid, renderState.toStdString()); } /**jsdoc - * Get the most recent pick result from this Pointer. This will be updated as long as the Pointer is enabled, regardless of the render state. + * Gets the most recent pick result from a pointer. A pointer continues to be updated ready to return a result, as long as + * it is enabled, regardless of the render state. * @function Pointers.getPrevPickResult - * @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}. - * @returns {RayPickResult|StylusPickResult} The most recent intersection result. This will be slightly different for different PickTypes. + * @param {number} id - The ID of the pointer. + * @returns {RayPickResult|ParabolaPickResult|StylusPickResult} The most recent intersection result. */ Q_INVOKABLE QVariantMap getPrevPickResult(unsigned int uid) const; /**jsdoc - * Sets whether or not to use precision picking. + * Sets whether or not a pointer should use precision picking, i.e., whether it should pick against precise meshes or + * coarse meshes. This has the same effect as using the PICK_PRECISE or PICK_COARSE filter flags. * @function Pointers.setPrecisionPicking - * @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}. - * @param {boolean} precisionPicking Whether or not to use precision picking + * @param {number} id - The ID of the pointer. + * @param {boolean} precisionPicking - true to use precision picking, false to use coarse picking. */ Q_INVOKABLE void setPrecisionPicking(unsigned int uid, bool precisionPicking) const { DependencyManager::get()->setPrecisionPicking(uid, precisionPicking); } /**jsdoc - * Sets the length of this Pointer. No effect on Stylus Pointers. + * Sets the length of a pointer. + *

Note: Not used by stylus pointers.

* @function Pointers.setLength - * @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}. - * @param {number} length The desired length of the Pointer. + * @param {number} id - The ID of the pointer. + * @param {number} length - The desired length of the pointer. */ Q_INVOKABLE void setLength(unsigned int uid, float length) const { DependencyManager::get()->setLength(uid, length); } /**jsdoc - * Sets a list of Entity IDs and/or Avatar IDs to ignore during intersection. Not used by Stylus Pointers. + * Sets a list of entity and avatar IDs that a pointer should ignore during intersection. + *

Note: Not used by stylus pointers.

* @function Pointers.setIgnoreItems - * @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}. - * @param {Uuid[]} ignoreItems A list of IDs to ignore. + * @param {number} id - The ID of the pointer. + * @param {Uuid[]} ignoreItems - A list of IDs to ignore. */ Q_INVOKABLE void setIgnoreItems(unsigned int uid, const QScriptValue& ignoreEntities) const; /**jsdoc - * Sets a list of Entity IDs and/or Avatar IDs to include during intersection, instead of intersecting with everything. Stylus - * Pointers only intersect with objects in their include list. + * Sets a list of entity and avatar IDs that a pointer should include during intersection, instead of intersecting with + * everything. + *

Note: Stylus pointers only intersect with items in their include list.

* @function Pointers.setIncludeItems - * @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}. - * @param {Uuid[]} includeItems A list of IDs to include. + * @param {number} id - The ID of the pointer. + * @param {Uuid[]} includeItems - A list of IDs to include. */ Q_INVOKABLE void setIncludeItems(unsigned int uid, const QScriptValue& includeEntities) const; /**jsdoc - * Lock a Pointer onto a specific object (entity or avatar). Optionally, provide an offset in object-space, otherwise the Pointer will lock on to the center of the object. - * Not used by Stylus Pointers. + * Locks a pointer onto a specific entity or avatar. + *

Note: Not used by stylus pointers.

* @function Pointers.setLockEndUUID - * @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}. - * @param {Uuid} objectID The ID of the object to which to lock on. - * @param {boolean} isAvatar False for entities, true for avatars - * @param {Mat4} [offsetMat] The offset matrix to use if you do not want to lock on to the center of the object. + * @param {number} id - The ID of the pointer. + * @param {Uuid} targetID - The ID of the entity or avatar to lock the pointer on to. + * @param {boolean} isAvatar - true if the target is an avatar, false if it is an entity. + * @param {Mat4} [offset] - The offset of the target point from the center of the target item. If not specified, the + * pointer locks on to the center of the target item. */ Q_INVOKABLE void setLockEndUUID(unsigned int uid, const QUuid& objectID, bool isAvatar, const glm::mat4& offsetMat = glm::mat4()) const { DependencyManager::get()->setLockEndUUID(uid, objectID, isAvatar, offsetMat); } /**jsdoc - * Check if a Pointer is associated with the left hand. + * Checks if a pointer is associated with the left hand: a ray or parabola pointer with joint property set to + * "_CONTROLLER_LEFTHAND" or "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", or a stylus pointer with + * hand property set to 0. * @function Pointers.isLeftHand - * @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}. - * @returns {boolean} True if the Pointer is a Joint Ray Pointer with joint == "_CONTROLLER_LEFTHAND" or "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", or a Stylus Pointer with hand == 0 + * @param {number} id - The ID of the pointer. + * @returns {boolean} true if the pointer is associated with the left hand, false if it isn't. */ Q_INVOKABLE bool isLeftHand(unsigned int uid) { return DependencyManager::get()->isLeftHand(uid); } /**jsdoc - * Check if a Pointer is associated with the right hand. + * Checks if a pointer is associated with the right hand: a ray or parabola pointer with joint property set to + * "_CONTROLLER_RIGHTHAND" or "_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND", or a stylus pointer with + * hand property set to 1. * @function Pointers.isRightHand - * @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}. - * @returns {boolean} True if the Pointer is a Joint Ray Pointer with joint == "_CONTROLLER_RIGHTHAND" or "_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND", or a Stylus Pointer with hand == 1 + * @param {number} id - The ID of the pointer. + * @returns {boolean} true if the pointer is associated with the right hand, false if it isn't. */ Q_INVOKABLE bool isRightHand(unsigned int uid) { return DependencyManager::get()->isRightHand(uid); } /**jsdoc - * Check if a Pointer is associated with the system mouse. + * Checks if a pointer is associated with the system mouse: a ray or parabola pointer with joint property set + * to "Mouse". * @function Pointers.isMouse - * @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}. - * @returns {boolean} True if the Pointer is a Mouse Ray Pointer, false otherwise. + * @param {number} id - The ID of the pointer. + * @returns {boolean} true if the pointer is associated with the system mouse, false if it isn't. */ Q_INVOKABLE bool isMouse(unsigned int uid) { return DependencyManager::get()->isMouse(uid); } /**jsdoc - * Returns information about an existing Pointer + * Gets information about a pointer. * @function Pointers.getPointerProperties - * @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}. - * @returns {Pointers.LaserPointerProperties|Pointers.StylusPointerProperties|Pointers.ParabolaPointerProperties} The information about the Pointer. - * Currently only includes renderStates and defaultRenderStates with associated entity IDs. + * @param {number} id - The ID of the pointer. + * @returns {Pointers.RayPointerProperties|Pointers.ParabolaPointerProperties|{}} The renderStates and + * defaultRenderStates for ray and parabola pointers, {} for stylus pointers. + * @example Report the properties of a parabola pointer. + * var intersectEnd = { + * type: "sphere", + * dimensions: { x: 0.2, y: 0.2, z: 0.2 }, + * solid: true, + * color: { red: 0, green: 255, blue: 0 }, + * ignorePickIntersection: true + * }; + * var intersectedPath = { + * color: { red: 0, green: 255, blue: 0 }, + * }; + * var searchEnd = { + * type: "sphere", + * dimensions: { x: 0.2, y: 0.2, z: 0.2 }, + * solid: true, + * color: { red: 255, green: 0, blue: 0 }, + * ignorePickIntersection: true + * }; + * var searchPath = { + * color: { red: 255, green: 0, blue: 0 }, + * }; + * + * var renderStates = [{ name: "example", path: intersectedPath, end: intersectEnd }]; + * var defaultRenderStates = [{ name: "example", distance: 20.0, path: searchPath, end: searchEnd }]; + * + * // Create the pointer. + * var parabolaPointer = Pointers.createPointer(PickType.Parabola, { + * joint: "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", + * filter: Picks.PICK_LOCAL_ENTITIES | Picks.PICK_DOMAIN_ENTITIES | Picks.PICK_INCLUDE_NONCOLLIDABLE, + * renderStates: renderStates, + * defaultRenderStates: defaultRenderStates, + * enabled: true + * }); + * Pointers.setRenderState(parabolaPointer, "example"); + * + * // Report the pointer properties. + * Script.setTimeout(function () { + * var properties = Pointers.getPointerProperties(parabolaPointer); + * print("Pointer properties:" + JSON.stringify(properties)); + * }, 500); + * + * // Tidy up. + * Script.scriptEnding.connect(function () { + * Pointers.removePointer(parabolaPointer); + * }); */ Q_INVOKABLE QVariantMap getPointerProperties(unsigned int uid) const; }; From e109c8f6d310356d678d85ea3f4ebf2b1cb7a180 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 2 Jul 2019 08:13:12 +1200 Subject: [PATCH 2/6] Picks and RayPick API JSdoc updates per Pointers API JSDoc --- .../src/raypick/PickScriptingInterface.cpp | 8 +++--- .../src/raypick/PickScriptingInterface.h | 25 +++++++++++-------- .../src/raypick/RayPickScriptingInterface.h | 23 +++++++++-------- 3 files changed, 31 insertions(+), 25 deletions(-) diff --git a/interface/src/raypick/PickScriptingInterface.cpp b/interface/src/raypick/PickScriptingInterface.cpp index 82d00d803f..c01455a3e3 100644 --- a/interface/src/raypick/PickScriptingInterface.cpp +++ b/interface/src/raypick/PickScriptingInterface.cpp @@ -55,7 +55,7 @@ PickFilter getPickFilter(unsigned int filter) { } /**jsdoc - * A set of properties that can be passed to {@link Picks.createPick} when creating a new ray pick. + * The properties of a ray pick. * * @typedef {object} Picks.RayPickProperties * @property {boolean} [enabled=false] - true if this pick should start enabled, false if it should @@ -138,7 +138,7 @@ unsigned int PickScriptingInterface::createRayPick(const QVariant& properties) { } /**jsdoc - * A set of properties that can be passed to {@link Picks.createPick} when creating a new stylus pick. + * The properties of a stylus pick. * * @typedef {object} Picks.StylusPickProperties * @property {number} [hand=-1] 0 for the left hand, 1 for the right hand, invalid (-1) @@ -189,7 +189,7 @@ unsigned int PickScriptingInterface::createStylusPick(const QVariant& properties // NOTE: Laser pointer still uses scaleWithAvatar. Until scaleWithAvatar is also deprecated for pointers, scaleWithAvatar should not be removed from the pick API. /**jsdoc - * A set of properties that can be passed to {@link Picks.createPick} when creating a new parabola pick. + * The properties of a parabola pick. * * @typedef {object} Picks.ParabolaPickProperties * @property {boolean} [enabled=false] - true if this pick should start enabled, false if it should @@ -297,7 +297,7 @@ unsigned int PickScriptingInterface::createParabolaPick(const QVariant& properti /**jsdoc - * A set of properties that can be passed to {@link Picks.createPick} when creating a new collision pick. + * The properties or a collision pick. * * @typedef {object} Picks.CollisionPickProperties * @property {boolean} [enabled=false] - true if this pick should start enabled, false if it should diff --git a/interface/src/raypick/PickScriptingInterface.h b/interface/src/raypick/PickScriptingInterface.h index 1cbdaa92f7..e973ee3643 100644 --- a/interface/src/raypick/PickScriptingInterface.h +++ b/interface/src/raypick/PickScriptingInterface.h @@ -194,7 +194,8 @@ public: Q_INVOKABLE QVariantMap getPrevPickResult(unsigned int uid); /**jsdoc - * Sets whether or not to use precision picking, i.e., whether to pick against precise meshes or coarse meshes. + * Sets whether or not a pick should use precision picking, i.e., whether it should pick against precise meshes or coarse + * meshes. * This has the same effect as using the PICK_PRECISE or PICK_COARSE filter flags. * @function Picks.setPrecisionPicking * @param {number} id - The ID of the pick. @@ -203,7 +204,7 @@ public: Q_INVOKABLE void setPrecisionPicking(unsigned int uid, bool precisionPicking); /**jsdoc - * Sets a list of entity and avatar IDs to ignore during intersection. + * Sets a list of entity and avatar IDs that a pick should ignore during intersection. *

Note: Not used by stylus picks.

* @function Picks.setIgnoreItems * @param {number} id - The ID of the pick. @@ -212,8 +213,9 @@ public: Q_INVOKABLE void setIgnoreItems(unsigned int uid, const QScriptValue& ignoreItems); /**jsdoc - * Sets a list of entity IDs and/or avatar IDs to include during intersection, instead of intersecting with everything. - *

Note: Stylus picks only intersect with objects in their include list.

+ * Sets a list of entity and avatar IDs that a pick should include during intersection, instead of intersecting with + * everything. + *

Note: Stylus picks only intersect with items in their include list.

* @function Picks.setIncludeItems * @param {number} id - The ID of the pick. * @param {Uuid[]} includeItems - The list of IDs to include. @@ -221,9 +223,9 @@ public: Q_INVOKABLE void setIncludeItems(unsigned int uid, const QScriptValue& includeItems); /**jsdoc - * Checks if a pick is associated with the left hand: a ray or parabola pick with joint set to - * "_CONTROLLER_LEFTHAND" or "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", or a stylus pick with hand - * set to 0. + * Checks if a pick is associated with the left hand: a ray or parabola pick with joint property set to + * "_CONTROLLER_LEFTHAND" or "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", or a stylus pick with + * hand property set to 0. * @function Picks.isLeftHand * @param {number} id - The ID of the pick. * @returns {boolean} true if the pick is associated with the left hand, false if it isn't. @@ -231,9 +233,9 @@ public: Q_INVOKABLE bool isLeftHand(unsigned int uid); /**jsdoc - * Checks if a pick is associated with the right hand: a ray or parabola pick with joint set to - * "_CONTROLLER_RIGHTHAND" or "_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND", or a stylus pick with hand - * set to 1. + * Checks if a pick is associated with the right hand: a ray or parabola pick with joint property set to + * "_CONTROLLER_RIGHTHAND" or "_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND", or a stylus pick with + * hand property set to 1. * @function Picks.isRightHand * @param {number} id - The ID of the pick. * @returns {boolean} true if the pick is associated with the right hand, false if it isn't. @@ -241,7 +243,8 @@ public: Q_INVOKABLE bool isRightHand(unsigned int uid); /**jsdoc - * Checks if a pick is associated with the system mouse: a ray or parabola pick with joint set to "Mouse". + * Checks if a pick is associated with the system mouse: a ray or parabola pick with joint property set to + * "Mouse". * @function Picks.isMouse * @param {number} id - The ID of the pick. * @returns {boolean} true if the pick is associated with the system mouse, false if it isn't. diff --git a/interface/src/raypick/RayPickScriptingInterface.h b/interface/src/raypick/RayPickScriptingInterface.h index 32a2ec4a5d..2a00847510 100644 --- a/interface/src/raypick/RayPickScriptingInterface.h +++ b/interface/src/raypick/RayPickScriptingInterface.h @@ -107,7 +107,8 @@ public: /**jsdoc - * Sets whether or not to use precision picking, i.e., whether to pick against precise meshes or coarse meshes. + * Sets whether or not a ray pick should use precision picking, i.e., whether it should pick against precise meshes or + * coarse meshes. * @function RayPick.setPrecisionPicking * @param {number} id - The ID of the ray pick. * @param {boolean} precisionPicking - true to use precision picking, false to use coarse picking. @@ -115,7 +116,7 @@ public: Q_INVOKABLE void setPrecisionPicking(unsigned int uid, bool precisionPicking); /**jsdoc - * Sets a list of entity and avatar IDs to ignore during intersection. + * Sets a list of entity and avatar IDs that a ray pick should ignore during intersection. * @function RayPick.setIgnoreItems * @param {number} id - The ID of the ray pick. * @param {Uuid[]} ignoreItems - The list of IDs to ignore. @@ -123,7 +124,8 @@ public: Q_INVOKABLE void setIgnoreItems(unsigned int uid, const QScriptValue& ignoreEntities); /**jsdoc - * Sets a list of entity IDs and/or avatar IDs to include during intersection, instead of intersecting with everything. + * Sets a list of entity and avatar IDs that a ray pick should include during intersection, instead of intersecting with + * everything. * @function RayPick.setIncludeItems * @param {number} id - The ID of the ray pick. * @param {Uuid[]} includeItems - The list of IDs to include. @@ -132,9 +134,9 @@ public: /**jsdoc - * Checks if a pick is associated with the left hand: a ray or parabola pick with joint set to - * "_CONTROLLER_LEFTHAND" or "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", or a stylus pick with hand - * set to 0. + * Checks if a pick is associated with the left hand: a ray or parabola pick with joint property set to + * "_CONTROLLER_LEFTHAND" or "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", or a stylus pick with + * hand property set to 0. * @function RayPick.isLeftHand * @param {number} id - The ID of the ray pick. * @returns {boolean} true if the pick is associated with the left hand, false if it isn't. @@ -142,9 +144,9 @@ public: Q_INVOKABLE bool isLeftHand(unsigned int uid); /**jsdoc - * Checks if a pick is associated with the right hand: a ray or parabola pick with joint set to - * "_CONTROLLER_RIGHTHAND" or "_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND", or a stylus pick with hand - * set to 1. + * Checks if a pick is associated with the right hand: a ray or parabola pick with joint property set to + * "_CONTROLLER_RIGHTHAND" or "_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND", or a stylus pick with + * hand property set to 1. * @function RayPick.isRightHand * @param {number} id - The ID of the ray pick. * @returns {boolean} true if the pick is associated with the right hand, false if it isn't. @@ -152,7 +154,8 @@ public: Q_INVOKABLE bool isRightHand(unsigned int uid); /**jsdoc - * Checks if a pick is associated with the system mouse: a ray or parabola pick with joint set to "Mouse". + * Checks if a pick is associated with the system mouse: a ray or parabola pick with joint property set to + * "Mouse". * @function RayPick.isMouse * @param {number} id - The ID of the ray pick. * @returns {boolean} true if the pick is associated with the system mouse, false if it isn't. From b7e92e099410e079c0bfcca882255737ace98f27 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 2 Jul 2019 16:02:33 +1200 Subject: [PATCH 3/6] LaserPointers API JSDoc update --- .../raypick/LaserPointerScriptingInterface.h | 113 +++++++++++------- 1 file changed, 69 insertions(+), 44 deletions(-) diff --git a/interface/src/raypick/LaserPointerScriptingInterface.h b/interface/src/raypick/LaserPointerScriptingInterface.h index 425ffd7de4..6c5ce0dbaf 100644 --- a/interface/src/raypick/LaserPointerScriptingInterface.h +++ b/interface/src/raypick/LaserPointerScriptingInterface.h @@ -21,121 +21,146 @@ class LaserPointerScriptingInterface : public QObject, public Dependency { SINGLETON_DEPENDENCY /**jsdoc - * Synonym for {@link Pointers} as used for laser pointers. Deprecated. + * The LaserPointers API is a subset of the {@link Pointers} API. It lets you create, manage, and visually + * represent objects for repeatedly calculating ray intersections with avatars, entities, and overlays. Ray pointers can also + * be configured to generate events on entities and overlays intersected. + * + *

Deprecated: This API is deprecated. Use {@link Pointers} instead. * * @namespace LaserPointers * * @hifi-interface * @hifi-client-entity * @hifi-avatar + * + * @borrows Pointers.enablePointer as enableLaserPointer + * @borrows Pointers.disablePointer as disableLaserPointer + * @borrows Pointers.removePointer as removeLaserPointer + * @borrows Pointers.setPrecisionPicking as setPrecisionPicking */ public: /**jsdoc + * Creates a new ray pointer. The pointer can have a wide range of behaviors depending on the properties specified. For + * example, it may be a static ray pointer, a mouse ray pointer, or joint ray pointer. + *

Warning: Pointers created using this method currently always intersect at least visible and + * collidable things but this may not always be the case.

* @function LaserPointers.createLaserPointer - * @param {Pointers.LaserPointerProperties} properties - * @returns {number} + * @param {Pointers.RayPointerProperties} properties - The properties of the pointer, including the properties of the + * underlying pick that the pointer uses to do its picking. + * @returns {number} The ID of the pointer if successfully created, otherwise 0. */ Q_INVOKABLE unsigned int createLaserPointer(const QVariant& properties) const; - /**jsdoc - * @function LaserPointers.enableLaserPointer - * @param {number} id - */ + // jsdoc @borrows from Pointers Q_INVOKABLE void enableLaserPointer(unsigned int uid) const { DependencyManager::get()->enablePointer(uid); } - /**jsdoc - * @function LaserPointers.disableLaserPointer - * @param {number} id - */ + // jsdoc @borrows from Pointers Q_INVOKABLE void disableLaserPointer(unsigned int uid) const { DependencyManager::get()->disablePointer(uid); } - /**jsdoc - * @function LaserPointers.removeLaserPointer - * @param {number} id - */ + // jsdoc @borrows from Pointers Q_INVOKABLE void removeLaserPointer(unsigned int uid) const { DependencyManager::get()->removePointer(uid); } /**jsdoc + * Edits a render state of a pointer, to change its visual appearance for the state when the pointer is intersecting + * something. + *

Note: You can only edit the properties of the existing parts of the pointer; you cannot change the + * type of any part.

+ *

Note: You cannot use this method to change the appearance of a default render state.

* @function LaserPointers.editRenderState - * @param {number} id - * @param {string} renderState - * @param {Pointers.RayPointerRenderState} properties + * @param {number} id - The ID of the pointer. + * @param {string} renderState - The name of the render state to edit. + * @param {Pointers.RayPointerRenderState} properties - The new properties for the render state. Only the overlay + * properties to change need be specified. */ Q_INVOKABLE void editRenderState(unsigned int uid, const QString& renderState, const QVariant& properties) const; /**jsdoc + * Sets the render state of a pointer, to change its visual appearance and possibly disable or enable it. * @function LaserPointers.setRenderState - * @param {string} renderState - * @param {number} id + * @param {string} renderState -

The name of the render state to set the pointer to. This may be:

+ *
    + *
  • The name of one of the render states set in the pointer's properties.
    • + *
  • "", to hide the pointer and disable emitting of events.
    • + *
+ * @param {number} id - The ID of the pointer. */ Q_INVOKABLE void setRenderState(unsigned int uid, const QString& renderState) const { DependencyManager::get()->setRenderState(uid, renderState.toStdString()); } /**jsdoc + * Gets the most recent intersection of a pointer. A pointer continues to be updated ready to return a result, as long as + * it is enabled, regardless of the render state. * @function LaserPointers.getPrevRayPickResult - * @param {number} id - * @returns {RayPickResult} + * @param {number} id - The ID of the pointer. + * @returns {RayPickResult} The most recent intersection of the pointer. */ Q_INVOKABLE QVariantMap getPrevRayPickResult(unsigned int uid) const; - - /**jsdoc - * @function LaserPointers.setPrecisionPicking - * @param {number} id - * @param {boolean} precisionPicking - */ + // jsdoc @borrows from Pointers Q_INVOKABLE void setPrecisionPicking(unsigned int uid, bool precisionPicking) const { DependencyManager::get()->setPrecisionPicking(uid, precisionPicking); } /**jsdoc + * Sets the length of a pointer. * @function LaserPointers.setLaserLength - * @param {number} id - * @param {number} laserLength + * @param {number} id - The ID of the pointer. + * @param {number} laserLength - The desired length of the pointer. */ Q_INVOKABLE void setLaserLength(unsigned int uid, float laserLength) const { DependencyManager::get()->setLength(uid, laserLength); } /**jsdoc + * Sets a list of entity and avatar IDs that a pointer should ignore during intersection. * @function LaserPointers.setIgnoreItems - * @param {number} id - * @param {Uuid[]} ignoreItems + * @param {number} id - The ID of the pointer. + * @param {Uuid[]} ignoreItems - A list of IDs to ignore. */ Q_INVOKABLE void setIgnoreItems(unsigned int uid, const QScriptValue& ignoreEntities) const; /**jsdoc + * Sets a list of entity and avatar IDs that a pointer should include during intersection, instead of intersecting with + * everything. * @function LaserPointers.setIncludeItems - * @param {number} id - * @param {Uuid[]} includeItems + * @param {number} id - The ID of the pointer. + * @param {Uuid[]} includeItems - A list of IDs to include. */ Q_INVOKABLE void setIncludeItems(unsigned int uid, const QScriptValue& includeEntities) const; /**jsdoc + * Locks a pointer onto a specific entity or avatar. * @function LaserPointers.setLockEndUUID - * @param {number} id - * @param {Uuid} itemID - * @param {boolean} isAvatar - * @param {Mat4} [offsetMat] + * @param {number} id - The ID of the pointer. + * @param {Uuid} targetID - The ID of the entity or avatar to lock the pointer on to. + * @param {boolean} isAvatar - true if the target is an avatar, false if it is an entity. + * @param {Mat4} [offset] - The offset of the target point from the center of the target item. If not specified, the + * pointer locks on to the center of the target item. */ Q_INVOKABLE void setLockEndUUID(unsigned int uid, const QUuid& objectID, bool isAvatar, const glm::mat4& offsetMat = glm::mat4()) const { DependencyManager::get()->setLockEndUUID(uid, objectID, isAvatar, offsetMat); } /**jsdoc + * Checks if a pointer is associated with the left hand: a pointer with joint property set to + * "_CONTROLLER_LEFTHAND" or "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND". * @function LaserPointers.isLeftHand - * @param {number} id - * @returns {boolean} + * @param {number} id - The ID of the pointer. + * @returns {boolean} true if the pointer is associated with the left hand, false if it isn't. */ Q_INVOKABLE bool isLeftHand(unsigned int uid) { return DependencyManager::get()->isLeftHand(uid); } /**jsdoc + * Checks if a pointer is associated with the right hand: a pointer with joint property set to + * "_CONTROLLER_RIGHTHAND" or "_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND". * @function LaserPointers.isRightHand - * @param {number} id - * @returns {boolean} + * @param {number} id - The ID of the pointer. + * @returns {boolean} true if the pointer is associated with the right hand, false if it isn't. */ Q_INVOKABLE bool isRightHand(unsigned int uid) { return DependencyManager::get()->isRightHand(uid); } /**jsdoc + * Checks if a pointer is associated with the system mouse: a pointer with joint property set to + * "Mouse". * @function LaserPointers.isMouse - * @param {number} id - * @returns {boolean} + * @param {number} id - The ID of the pointer. + * @returns {boolean} true if the pointer is associated with the system mouse, false if it isn't. */ Q_INVOKABLE bool isMouse(unsigned int uid) { return DependencyManager::get()->isMouse(uid); } }; From c6fd726111953e484e7829e0f85fc20f44bffaaf Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 2 Jul 2019 16:07:39 +1200 Subject: [PATCH 4/6] Typos etc. --- interface/src/raypick/PointerScriptingInterface.cpp | 3 ++- interface/src/raypick/PointerScriptingInterface.h | 8 ++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/interface/src/raypick/PointerScriptingInterface.cpp b/interface/src/raypick/PointerScriptingInterface.cpp index d904706b08..5bff7d4589 100644 --- a/interface/src/raypick/PointerScriptingInterface.cpp +++ b/interface/src/raypick/PointerScriptingInterface.cpp @@ -54,7 +54,8 @@ unsigned int PointerScriptingInterface::createPointer(const PickQuery::PickType& * The properties of a stylus pointer. These include the properties from the underlying stylus pick that the pointer uses. * @typedef {object} Pointers.StylusPointerProperties * @property {Pointers.StylusPointerModel} [model] - Override some or all of the default stylus model properties. - * @property {boolean} [hover=false] - If true, the pointer generates {@link Entities} hover events. + * @property {boolean} [hover=false] - true if the pointer generates {@link Entities} hover events, + * false if it doesn't. * @see {@link Picks.StylusPickProperties} for additional properties from the underlying stylus pick. */ /**jsdoc diff --git a/interface/src/raypick/PointerScriptingInterface.h b/interface/src/raypick/PointerScriptingInterface.h index 58959570ab..823767467e 100644 --- a/interface/src/raypick/PointerScriptingInterface.h +++ b/interface/src/raypick/PointerScriptingInterface.h @@ -53,7 +53,7 @@ public: */ /**jsdoc - * Creates a new ray, parabola, or stylus pointer. The pointers can have a wide range of behaviors depending on the + * Creates a new ray, parabola, or stylus pointer. The pointer can have a wide range of behaviors depending on the * properties specified. For example, a ray pointer may be a static ray pointer, a mouse ray pointer, or joint ray * pointer. *

Warning: Pointers created using this method currently always intersect at least visible and @@ -306,11 +306,11 @@ public: /**jsdoc - * Gets the most recent pick result from a pointer. A pointer continues to be updated ready to return a result, as long as + * Gets the most recent intersection of a pointer. A pointer continues to be updated ready to return a result, as long as * it is enabled, regardless of the render state. * @function Pointers.getPrevPickResult * @param {number} id - The ID of the pointer. - * @returns {RayPickResult|ParabolaPickResult|StylusPickResult} The most recent intersection result. + * @returns {RayPickResult|ParabolaPickResult|StylusPickResult} The most recent intersection of the pointer. */ Q_INVOKABLE QVariantMap getPrevPickResult(unsigned int uid) const; @@ -399,7 +399,7 @@ public: * Gets information about a pointer. * @function Pointers.getPointerProperties * @param {number} id - The ID of the pointer. - * @returns {Pointers.RayPointerProperties|Pointers.ParabolaPointerProperties|{}} The renderStates and + * @returns {Pointers.RayPointerProperties|Pointers.ParabolaPointerProperties|object} The renderStates and * defaultRenderStates for ray and parabola pointers, {} for stylus pointers. * @example Report the properties of a parabola pointer. * var intersectEnd = { From 5c29eb04b388748d5baaf2620b424d4be5d72757 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 2 Jul 2019 16:19:32 +1200 Subject: [PATCH 5/6] Typo --- interface/src/raypick/PickScriptingInterface.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/interface/src/raypick/PickScriptingInterface.cpp b/interface/src/raypick/PickScriptingInterface.cpp index c01455a3e3..12f68c1430 100644 --- a/interface/src/raypick/PickScriptingInterface.cpp +++ b/interface/src/raypick/PickScriptingInterface.cpp @@ -297,7 +297,7 @@ unsigned int PickScriptingInterface::createParabolaPick(const QVariant& properti /**jsdoc - * The properties or a collision pick. + * The properties of a collision pick. * * @typedef {object} Picks.CollisionPickProperties * @property {boolean} [enabled=false] - true if this pick should start enabled, false if it should From 8fb83e98be85753d679ffc6491a6f9e32e7be911 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 4 Jul 2019 20:02:42 +1200 Subject: [PATCH 6/6] Doc review. --- interface/src/raypick/PointerScriptingInterface.cpp | 8 ++++---- interface/src/raypick/PointerScriptingInterface.h | 4 ++-- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/interface/src/raypick/PointerScriptingInterface.cpp b/interface/src/raypick/PointerScriptingInterface.cpp index 5bff7d4589..f1dcf7bd5d 100644 --- a/interface/src/raypick/PointerScriptingInterface.cpp +++ b/interface/src/raypick/PointerScriptingInterface.cpp @@ -140,8 +140,8 @@ unsigned int PointerScriptingInterface::createStylus(const QVariant& properties) * @property {boolean} [faceAvatar=false] - true if the overlay rendered at the end of the ray rotates about the * world y-axis to always face the avatar; false if it maintains its world orientation. * @property {boolean} [centerEndY=true] - true if the overlay rendered at the end of the ray is centered on - * the ray end; false if the overlay is rendered adjacent to the surface if followNormal is - * true or on top of the ray end if if followNormal is false. + * the ray end; false if the overlay is positioned against the surface if followNormal is + * true, or above the ray end if followNormal is false. * @property {boolean} [lockEnd=false] - true if the end of the ray is locked to the center of the object at * which the ray is pointing; false if the end of the ray is at the intersected surface. * @property {boolean} [distanceScaleEnd=false] - true if the dimensions of the overlay at the end of the ray @@ -331,8 +331,8 @@ unsigned int PointerScriptingInterface::createLaserPointer(const QVariant& prope * @property {boolean} [faceAvatar=false] - true if the overlay rendered at the end of the ray rotates about the * world y-axis to always face the avatar; false if it maintains its world orientation. * @property {boolean} [centerEndY=true] - true if the overlay rendered at the end of the ray is centered on - * the ray end; false if the overlay is rendered adjacent to the surface if followNormal is - * true or on top of the ray end if if followNormal is false. + * the ray end; false if the overlay is positioned against the surface if followNormal is + * true, or above the ray end if followNormal is false. * @property {boolean} [lockEnd=false] - true if the end of the ray is locked to the center of the object at * which the ray is pointing; false if the end of the ray is at the intersected surface. * @property {boolean} [distanceScaleEnd=false] - true if the dimensions of the overlay at the end of the ray diff --git a/interface/src/raypick/PointerScriptingInterface.h b/interface/src/raypick/PointerScriptingInterface.h index 823767467e..e6efaae09f 100644 --- a/interface/src/raypick/PointerScriptingInterface.h +++ b/interface/src/raypick/PointerScriptingInterface.h @@ -41,8 +41,8 @@ public: * pointer. * @typedef {object} Pointers.Trigger * @property {Controller.Standard|Controller.Actions|function} action - The controller output or function that triggers the - * events on the entity or overlay. If a function, it must return a number >= 1.0 to start the action and - * < 1.0 to terminate the action. + * events on the entity or overlay. If a function, it must return a number >= 1.0 to start the action + * and < 1.0 to terminate the action. * @property {string} button - Which button to trigger. *

    *
  • "Primary", "Secondary", and "Tertiary" cause {@link Entities} and