diff --git a/interface/src/raypick/CollisionPick.cpp b/interface/src/raypick/CollisionPick.cpp index 82d75257df..b3888ae3a0 100644 --- a/interface/src/raypick/CollisionPick.cpp +++ b/interface/src/raypick/CollisionPick.cpp @@ -57,6 +57,37 @@ void buildObjectIntersectionsMap(IntersectionType intersectionType, const std::v } } +/**jsdoc + * An intersection result for a collision pick. + * + * @typedef {object} CollisionPickResult + * @property {boolean} intersects - truen if there is at least one intersection, false if there isn't. + * @property {IntersectingObject[]} intersectingObjects - All objects which intersect with the collisionRegion. + * @property {CollisionRegion} collisionRegion - The collision region that was used. Valid even if there was no intersection. + */ + +/**jsdoc + * Information about a {@link CollisionPick}'s intersection with an object. + * + * @typedef {object} IntersectingObject + * @property {Uuid} id - The ID of the object. + * @property {IntersectionType} type - The type of the object, either 1 for INTERSECTED_ENTITY or 3 + * for INTERSECTED_AVATAR. + * @property {CollisionContact[]} collisionContacts - Information on the penetration between the pick and the object. + */ + +/**jsdoc + * A pair of points that represents part of an overlap between a {@link CollisionPick} and an object in the physics engine. + * Points which are further apart represent deeper overlap. + * + * @typedef {object} CollisionContact + * @property {Vec3} pointOnPick - A point representing a penetration of the object's surface into the volume of the pick, in + * world coordinates. + * @property {Vec3} pointOnObject - A point representing a penetration of the pick's surface into the volume of the object, in + * world coordinates. + * @property {Vec3} normalOnPick - The normal vector pointing away from the pick, representing the direction of collision. + */ + QVariantMap CollisionPickResult::toVariantMap() const { QVariantMap variantMap; diff --git a/interface/src/raypick/ParabolaPick.h b/interface/src/raypick/ParabolaPick.h index 0adbb01954..78c35e13b4 100644 --- a/interface/src/raypick/ParabolaPick.h +++ b/interface/src/raypick/ParabolaPick.h @@ -42,6 +42,23 @@ public: float parabolicDistance { FLT_MAX }; bool intersects { false }; + /**jsdoc + * An intersection result for a parabola pick. + * + * @typedef {object} ParabolaPickResult + * @property {number} type - The intersection type. + * @property {boolean} intersects - true if there's a valid intersection, false if there isn't. + * @property {Uuid} objectID - The ID of the intersected object. null for HUD or invalid intersections. + * @property {number} distance - The distance from the parabola origin to the intersection point in a straight line. + * @property {number} parabolicDistance - The distance from the parabola origin to the intersection point along the arc of + * the parabola. + * @property {Vec3} intersection - The intersection point in world coordinates. + * @property {Vec3} surfaceNormal - The surface normal at the intersected point. All NaNs if type == + * Picks.INTERSECTED_HUD. + * @property {SubmeshIntersection} extraInfo - Additional intersection details for model objects, otherwise + * { }. + * @property {PickParabola} parabola - The pick parabola that was used. Valid even if there is no intersection. + */ virtual QVariantMap toVariantMap() const override { QVariantMap toReturn; toReturn["type"] = type; diff --git a/interface/src/raypick/PickScriptingInterface.cpp b/interface/src/raypick/PickScriptingInterface.cpp index 09f4b68cb9..7e87ac22a7 100644 --- a/interface/src/raypick/PickScriptingInterface.cpp +++ b/interface/src/raypick/PickScriptingInterface.cpp @@ -55,23 +55,37 @@ PickFilter getPickFilter(unsigned int filter) { } /**jsdoc - * A set of properties that can be passed to {@link Picks.createPick} to create a new Ray Pick. + * A set of properties that can be passed to {@link Picks.createPick} when creating a new ray pick. + * * @typedef {object} Picks.RayPickProperties - * @property {boolean} [enabled=false] If this Pick should start enabled or not. Disabled Picks do not updated their pick results. - * @property {number} [filter=0] The filter for this Pick to use, constructed using filter flags combined using bitwise OR. - * @property {number} [maxDistance=0.0] The max distance at which this Pick will intersect. 0.0 = no max. < 0.0 is invalid. - * @property {Uuid} parentID - The ID of the parent, either an avatar, an entity, or a pick. - * @property {number} [parentJointIndex=0] - The joint of the parent to parent to, for example, the joints on the model of an avatar. (default = 0, no joint) - * @property {string} joint - If "Mouse," parents the pick to the mouse. If "Avatar," parents the pick to MyAvatar's head. Otherwise, parents to the joint of the given name on MyAvatar. - * @property {Vec3} [posOffset=Vec3.ZERO] Only for Joint Ray Picks. A local joint position offset, in meters. x = upward, y = forward, z = lateral - * @property {Vec3} [dirOffset=Vec3.UP] Only for Joint Ray Picks. A local joint direction offset. x = upward, y = forward, z = lateral - * @property {Vec3} [position] Only for Static Ray Picks. The world-space origin of the ray. - * @property {Vec3} [direction=-Vec3.UP] Only for Static Ray Picks. The world-space direction of the ray. + * @property {boolean} [enabled=false] - true if this pick should start enabled, false if it should + * start disabled. Disabled picks do not update their pick results. + * @property {FilterFlags} [filter=0] - The filter for this pick to use. Construct using {@link Picks} FilterFlags property + * values (e.g., Picks.PICK_DOMAIN_ENTTITIES) combined with | (bitwise OR) operators. + * @property {number} [maxDistance=0.0] - The maximum distance at which this pick will intersect. A value of 0.0 + * means no maximum. + * @property {Uuid} [parentID] - The ID of the parent: either an avatar, an entity, or another pick. + * @property {number} [parentJointIndex=0] - The joint of the parent to parent to, for example, an avatar joint. + * A value of 0 means no joint.
+ * Used only if parentID is specified. + * @property {string} [joint] - "Mouse" parents the pick to the mouse; "Avatar" parents the pick to + * the user's avatar head; a joint name parents to the joint in the user's avatar; otherwise the pick is "static", not + * parented to anything.
+ * Used only if parentID is not specified. + * @property {Vec3} [position=Vec3.ZERO] - The offset of the ray origin from its parent if parented, otherwise the ray origin + * in world coordinates. + * @property {Vec3} [posOffset] - Synonym for position. + * @property {Vec3} [direction] - The offset of the ray direction from its parent's y-axis if parented, otherwise the ray + * direction in world coordinates. + *

Default Value: Vec3.UP direction if joint is specified, otherwise + * -Vec3.UP.

+ * @property {Vec3} [dirOffset] - Synonym for direction. + * @property {Quat} [orientation] - Alternative property for specifying direction. The value is applied to the + * default direction value. */ unsigned int PickScriptingInterface::createRayPick(const QVariant& properties) { QVariantMap propMap = properties.toMap(); - #if defined (Q_OS_ANDROID) QString jointName { "" }; if (propMap["joint"].isValid()) { @@ -124,12 +138,20 @@ unsigned int PickScriptingInterface::createRayPick(const QVariant& properties) { } /**jsdoc - * A set of properties that can be passed to {@link Picks.createPick} to create a new Stylus Pick. + * A set of properties that can be passed to {@link Picks.createPick} when creating a new stylus pick. + * * @typedef {object} Picks.StylusPickProperties - * @property {number} [hand=-1] An integer. 0 == left, 1 == right. Invalid otherwise. - * @property {boolean} [enabled=false] If this Pick should start enabled or not. Disabled Picks do not updated their pick results. - * @property {number} [filter=0] The filter for this Pick to use, constructed using filter flags combined using bitwise OR. - * @property {number} [maxDistance=0.0] The max distance at which this Pick will intersect. 0.0 = no max. < 0.0 is invalid. + * @property {number} [hand=-1] 0 for the left hand, 1 for the right hand, invalid (-1) + * otherwise. + * @property {boolean} [enabled=false] - true if this pick should start enabled, false if it should + * start disabled. Disabled picks do not update their pick results. + * @property {number} [filter=0] - The filter for this pick to use. Construct using {@link Picks} FilterFlags property + * values (e.g., Picks.PICK_DOMAIN_ENTTITIES) combined with | (bitwise OR) operators. + *

Note: Stylus picks do not intersect avatars or the HUD.

+ * @property {number} [maxDistance=0.0] - The maximum distance at which this pick will intersect. A value of 0.0 + * means no maximum. + * @property {Vec3} [tipOffset=0,0.095,0] - The position of the stylus tip relative to the hand position at default avatar + * scale. */ unsigned int PickScriptingInterface::createStylusPick(const QVariant& properties) { QVariantMap propMap = properties.toMap(); @@ -167,23 +189,45 @@ 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} to create a new Parabola Pick. + * A set of properties that can be passed to {@link Picks.createPick} when creating a new parabola pick. + * * @typedef {object} Picks.ParabolaPickProperties - * @property {boolean} [enabled=false] If this Pick should start enabled or not. Disabled Picks do not updated their pick results. - * @property {number} [filter=0] The filter for this Pick to use, constructed using filter flags combined using bitwise OR. - * @property {number} [maxDistance=0.0] The max distance at which this Pick will intersect. 0.0 = no max. < 0.0 is invalid. - * @property {Uuid} parentID - The ID of the parent, either an avatar, an entity, or a pick. - * @property {number} [parentJointIndex=0] - The joint of the parent to parent to, for example, the joints on the model of an avatar. (default = 0, no joint) - * @property {string} joint - If "Mouse," parents the pick to the mouse. If "Avatar," parents the pick to MyAvatar's head. Otherwise, parents to the joint of the given name on MyAvatar. - * @property {Vec3} [posOffset=Vec3.ZERO] Only for Joint Parabola Picks. A local joint position offset, in meters. x = upward, y = forward, z = lateral - * @property {Vec3} [dirOffset=Vec3.UP] Only for Joint Parabola Picks. A local joint direction offset. x = upward, y = forward, z = lateral - * @property {Vec3} [position] Only for Static Parabola Picks. The world-space origin of the parabola segment. - * @property {Vec3} [direction=-Vec3.FRONT] Only for Static Parabola Picks. The world-space direction of the parabola segment. - * @property {number} [speed=1] The initial speed of the parabola, i.e. the initial speed of the projectile whose trajectory defines the parabola. - * @property {Vec3} [accelerationAxis=-Vec3.UP] The acceleration of the parabola, i.e. the acceleration of the projectile whose trajectory defines the parabola, both magnitude and direction. - * @property {boolean} [rotateAccelerationWithAvatar=true] Whether or not the acceleration axis should rotate with the avatar's local Y axis. - * @property {boolean} [rotateAccelerationWithParent=false] Whether or not the acceleration axis should rotate with the parent's local Y axis, if available. - * @property {boolean} [scaleWithParent=true] If true, the velocity and acceleration of the Pick will scale linearly with the parent, if available. scaleWithAvatar is an alias but is deprecated. + * @property {boolean} [enabled=false] - true if this pick should start enabled, false if it should + * start disabled. Disabled picks do not update their pick results. + * @property {number} [filter=0] - The filter for this pick to use. Construct using {@link Picks} FilterFlags property + * values (e.g., Picks.PICK_DOMAIN_ENTTITIES) combined with | (bitwise OR) operators. + * @property {number} [maxDistance=0.0] - The maximum distance at which this pick will intersect. A value of 0.0 + * means no maximum. + * @property {Uuid} [parentID] - The ID of the parent: either an avatar, an entity, or another pick. + * @property {number} [parentJointIndex=0] - The joint of the parent to parent to, for example, an avatar joint. + * A value of 0 means no joint.
+ * Used only if parentID is specified. + * @property {string} [joint] - "Mouse" parents the pick to the mouse; "Avatar" parents the pick to + * the user's avatar head; a joint name parents to the joint in the user's avatar; otherwise the pick is "static", not + * parented to anything. + * Used only if parentID is not specified. + * @property {Vec3} [position=Vec3.ZERO] - The offset of the parabola origin from its parent if parented, otherwise the + * parabola origin in world coordinates. + * @property {Vec3} [posOffset] - Synonym for position. + * @property {Vec3} [direction] - The offset of the parabola direction from its parent's y-axis if parented, otherwise the + * parabola direction in world coordinates. + *

Default Value: Vec3.UP direction if joint is specified, otherwise + * Vec3.FRONT.

+ * @property {Vec3} [dirOffset] - Synonym for direction. + * @property {Quat} [orientation] - Alternative property for specifying direction. The value is applied to the + * default direction value. + * @property {number} [speed=1] - The initial speed of the parabola in m/s, i.e., the initial speed of a virtual projectile + * whose trajectory defines the parabola. + * @property {Vec3} [accelerationAxis=-Vec3.UP] - The acceleration of the parabola in m/s2, i.e., the acceleration + * of a virtual projectile whose trajectory defines the parabola, both magnitude and direction. + * @property {boolean} [rotateAccelerationWithAvatar=true] - true if the acceleration axis should rotate with the + * avatar about the avatar's y-axis, false if it shouldn't. + * @property {boolean} [rotateAccelerationWithParent=false] - true if the acceleration axis should rotate with the + * parent about the parent's y-axis, if available. + * @property {boolean} [scaleWithParent=true] - true if the velocity and acceleration of the pick should scale + * with the avatar or other parent. + * @property {boolean} [scaleWithAvatar=true] - Synonym for scalewithParent. + *

Deprecated: This property is deprecated and will be removed.

*/ unsigned int PickScriptingInterface::createParabolaPick(const QVariant& properties) { QVariantMap propMap = properties.toMap(); @@ -251,35 +295,38 @@ unsigned int PickScriptingInterface::createParabolaPick(const QVariant& properti return DependencyManager::get()->addPick(PickQuery::Parabola, parabolaPick); } -/**jsdoc -* A Shape defines a physical volume. -* -* @typedef {object} Shape -* @property {string} shapeType The type of shape to use. Can be one of the following: "box", "sphere", "capsule-x", "capsule-y", "capsule-z", "cylinder-x", "cylinder-y", "cylinder-z" -* @property {Vec3} dimensions - The size to scale the shape to. -*/ - -// TODO: Add this property to the Shape jsdoc above once model picks work properly -// * @property {string} modelURL - If shapeType is one of: "compound", "simple-hull", "simple-compound", or "static-mesh", this defines the model to load to generate the collision volume. /**jsdoc -* A set of properties that can be passed to {@link Picks.createPick} to create a new Collision Pick. - -* @typedef {object} Picks.CollisionPickProperties -* @property {boolean} [enabled=false] If this Pick should start enabled or not. Disabled Picks do not updated their pick results. -* @property {number} [filter=0] The filter for this Pick to use, constructed using filter flags combined using bitwise OR. -* @property {Shape} shape - The information about the collision region's size and shape. Dimensions are in world space, but will scale with the parent if defined. -* @property {Vec3} position - The position of the collision region, relative to a parent if defined. -* @property {Quat} orientation - The orientation of the collision region, relative to a parent if defined. -* @property {float} threshold - The approximate minimum penetration depth for a test object to be considered in contact with the collision region. -* The depth is measured in world space, but will scale with the parent if defined. -* @property {CollisionMask} [collisionGroup=8] - The type of object this collision pick collides as. Objects whose collision masks overlap with the pick's collision group -* will be considered colliding with the pick. -* @property {Uuid} parentID - The ID of the parent, either an avatar, an entity, or a pick. -* @property {number} [parentJointIndex=0] - The joint of the parent to parent to, for example, the joints on the model of an avatar. (default = 0, no joint) -* @property {string} joint - If "Mouse," parents the pick to the mouse. If "Avatar," parents the pick to MyAvatar's head. Otherwise, parents to the joint of the given name on MyAvatar. -* @property {boolean} [scaleWithParent=true] If true, the collision pick's dimensions and threshold will adjust according to the scale of the parent. -*/ + * A set of properties that can be passed to {@link Picks.createPick} when creating a new collision pick. + * + * @typedef {object} Picks.CollisionPickProperties + * @property {boolean} [enabled=false] - true if this pick should start enabled, false if it should + * start disabled. Disabled picks do not update their pick results. + * @property {FilterFlags} [filter=0] - The filter for this pick to use. Construct using {@link Picks} FilterFlags property + * values (e.g., Picks.PICK_DOMAIN_ENTTITIES) combined with | (bitwise OR) operators. + *

Note: Collision picks do not intersect the HUD.

+ * @property {number} [maxDistance=0.0] - The maximum distance at which this pick will intersect. A value of 0.0 + * means no maximum. + * @property {Uuid} [parentID] - The ID of the parent: either an avatar, an entity, or another pick. + * @property {number} [parentJointIndex=0] - The joint of the parent to parent to, for example, an avatar joint. + * A value of 0 means no joint.
+ * Used only if parentID is specified. + * @property {string} [joint] - "Mouse" parents the pick to the mouse; "Avatar" parents the pick to + * the user's avatar head; a joint name parents to the joint in the user's avatar; otherwise the pick is "static", not + * parented to anything.
+ * Used only if parentID is not specified. + * @property {boolean} [scaleWithParent=true] - true to scale the pick's dimensions and threshold according to the + * scale of the parent. + * + * @property {Shape} shape - The collision region's shape and size. Dimensions are in world coordinates but scale with the + * parent if defined. + * @property {Vec3} position - The position of the collision region, relative to the parent if defined. + * @property {Quat} orientation - The orientation of the collision region, relative to the parent if defined. + * @property {number} threshold - The approximate minimum penetration depth for a test object to be considered in contact with + * the collision region. The depth is in world coordinates but scales with the parent if defined. + * @property {CollisionMask} [collisionGroup=8] - The type of objects the collision region collides as. Objects whose collision + * masks overlap with the regions's collision group are considered to be colliding with the region. + */ unsigned int PickScriptingInterface::createCollisionPick(const QVariant& properties) { QVariantMap propMap = properties.toMap(); diff --git a/interface/src/raypick/PickScriptingInterface.h b/interface/src/raypick/PickScriptingInterface.h index 6264a3e258..e544262b5f 100644 --- a/interface/src/raypick/PickScriptingInterface.h +++ b/interface/src/raypick/PickScriptingInterface.h @@ -17,7 +17,7 @@ #include /**jsdoc - * The Picks API lets you create and manage objects for repeatedly calculating intersections in different ways. + * The Picks API lets you create and manage objects for repeatedly calculating intersections. * * @namespace Picks * @@ -25,33 +25,43 @@ * @hifi-client-entity * @hifi-avatar * - * @property {number} PICK_ENTITIES A filter flag. Include domain and avatar entities when intersecting. Read-only.. Deprecated. - * @property {number} PICK_OVERLAYS A filter flag. Include local entities when intersecting. Read-only.. Deprecated. + * @property {FilterFlags} PICK_DOMAIN_ENTITIES - Include domain entities when intersecting. Read-only. + * @property {FilterFlags} PICK_AVATAR_ENTITIES - Include avatar entities when intersecting. Read-only. + * @property {FilterFlags} PICK_LOCAL_ENTITIES - Include local entities when intersecting. Read-only. + * @property {FilterFlags} PICK_AVATARS - Include avatars when intersecting. Read-only. + * @property {FilterFlags} PICK_HUD - Include the HUD sphere when intersecting in HMD mode. Read-only. * - * @property {number} PICK_DOMAIN_ENTITIES A filter flag. Include domain entities when intersecting. Read-only.. - * @property {number} PICK_AVATAR_ENTITIES A filter flag. Include avatar entities when intersecting. Read-only.. - * @property {number} PICK_LOCAL_ENTITIES A filter flag. Include local entities when intersecting. Read-only.. - * @property {number} PICK_AVATARS A filter flag. Include avatars when intersecting. Read-only.. - * @property {number} PICK_HUD A filter flag. Include the HUD sphere when intersecting in HMD mode. Read-only.. + * @property {FilterFlags} PICK_ENTITIES - Include domain and avatar entities when intersecting. Read-only. + *

Deprecated: Use PICK_DOMAIN_ENTITIES | PICK_AVATAR_ENTITIES + * instead.

+ * @property {FilterFlags} PICK_OVERLAYS - Include local entities when intersecting. Read-only. + *

Deprecated: Use PICK_LOCAL_ENTITIES instead.

* - * @property {number} PICK_INCLUDE_VISIBLE A filter flag. Include visible objects when intersecting. Read-only.. - * @property {number} PICK_INCLUDE_INVISIBLE A filter flag. Include invisible objects when intersecting. Read-only.. + * @property {FilterFlags} PICK_INCLUDE_VISIBLE - Include visible objects when intersecting. Read-only. + *

Warning: Is currently always enabled by default but may not be in the future.

+ * @property {FilterFlags} PICK_INCLUDE_INVISIBLE - Include invisible objects when intersecting. Read-only. * - * @property {number} PICK_INCLUDE_COLLIDABLE A filter flag. Include collidable objects when intersecting. Read-only.. - * @property {number} PICK_INCLUDE_NONCOLLIDABLE A filter flag. Include non-collidable objects when intersecting. Read-only.. + * @property {FilterFlags} PICK_INCLUDE_COLLIDABLE - Include collidable objects when intersecting. Read-only. + *

Warning: Is currently always enabled by default but may not be in the future.

+ * @property {FilterFlags} PICK_INCLUDE_NONCOLLIDABLE - Include non-collidable objects when intersecting. Read-only. * - * @property {number} PICK_PRECISE A filter flag. Pick against exact meshes. Read-only.. - * @property {number} PICK_COARSE A filter flag. Pick against coarse meshes. Read-only.. + * @property {FilterFlags} PICK_PRECISE - Pick against exact meshes. Read-only. + * @property {FilterFlags} PICK_COARSE - Pick against coarse meshes. Read-only. * - * @property {number} PICK_ALL_INTERSECTIONS Read-only.. + * @property {FilterFlags} PICK_ALL_INTERSECTIONS - If set, returns all intersections instead of just the closest. + * Read-only. + *

Warning: Not yet implemented.

* - * @property {number} INTERSECTED_NONE An intersection type. Intersected nothing with the given filter flags. Read-only. - * @property {number} INTERSECTED_ENTITY An intersection type. Intersected an entity. Read-only. - * @property {number} INTERSECTED_LOCAL_ENTITY An intersection type. Intersected a local entity. - * @property {number} INTERSECTED_OVERLAY An intersection type. Intersected an entity (3D Overlays no longer exist). Read-only. - * @property {number} INTERSECTED_AVATAR An intersection type. Intersected an avatar. Read-only. - * @property {number} INTERSECTED_HUD An intersection type. Intersected the HUD sphere. Read-only. - * @property {number} perFrameTimeBudget - The max number of usec to spend per frame updating Pick results. + * @property {IntersectionType} INTERSECTED_NONE - Intersected nothing. Read-only. + * @property {IntersectionType} INTERSECTED_ENTITY - Intersected an entity. Read-only. + * @property {IntersectionType} INTERSECTED_LOCAL_ENTITY - Intersected a local entity. Read-only. + * @property {IntersectionType} INTERSECTED_OVERLAY - Intersected a local entity. (3D overlays no longer exist.) + * Read-only. + *

Deprecated: Use INTERSECTED_LOCAL_ENTITY instead.

+ * @property {IntersectionType} INTERSECTED_AVATAR - Intersected an avatar. Read-only. + * @property {IntersectionType} INTERSECTED_HUD - Intersected the HUD sphere. Read-only. + * + * @property {number} perFrameTimeBudget - The maximum time, in microseconds, to spend per frame updating pick results. */ class PickScriptingInterface : public QObject, public Dependency { @@ -94,163 +104,145 @@ public: void registerMetaTypes(QScriptEngine* engine); /**jsdoc - * Adds a new Pick. - * 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 Pick, a Mouse Ray Pick, or a Joint Ray Pick. - * Picks created with this method always intersect at least visible and collidable things + * Creates a new pick. 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, the properties could + * configure a mouse ray pick, an avatar head ray pick, or a joint ray pick. + *

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

* @function Picks.createPick - * @param {PickType} type A PickType that specifies the method of picking to use - * @param {Picks.RayPickProperties|Picks.StylusPickProperties|Picks.ParabolaPickProperties|Picks.CollisionPickProperties} properties A PickProperties object, containing all the properties for initializing this Pick - * @returns {number} The ID of the created Pick. Used for managing the Pick. 0 if invalid. + * @param {PickType} type - The type of picking to use. + * @param {Picks.RayPickProperties|Picks.ParabolaPickProperties|Picks.StylusPickProperties|Picks.CollisionPickProperties} + * properties - Properties of the pick, per the pick type. + * @returns {number} The ID of the pick created. 0 if invalid. */ // TODO: expand Pointers to be able to be fully configurable with PickFilters Q_INVOKABLE unsigned int createPick(const PickQuery::PickType type, const QVariant& properties); /**jsdoc - * Enables a Pick. + * Enables a pick. enabled picks update their pick results. * @function Picks.enablePick - * @param {number} uid The ID of the Pick, as returned by {@link Picks.createPick}. + * @param {number} id - The ID of the pick. */ Q_INVOKABLE void enablePick(unsigned int uid); /**jsdoc - * Disables a Pick. + * Disables a pick. Disabled picks do not update their pick results. * @function Picks.disablePick - * @param {number} uid The ID of the Pick, as returned by {@link Picks.createPick}. + * @param {number} id - The ID of the pick. */ Q_INVOKABLE void disablePick(unsigned int uid); /**jsdoc - * Removes a Pick. + * Removes (deletes) a pick. * @function Picks.removePick - * @param {number} uid The ID of the Pick, as returned by {@link Picks.createPick}. + * @param {number} id - The ID of the pick. */ Q_INVOKABLE void removePick(unsigned int uid); /**jsdoc - * An intersection result for a Ray Pick. - * - * @typedef {object} RayPickResult - * @property {number} type The intersection type. - * @property {boolean} intersects If there was a valid intersection (type != INTERSECTED_NONE) - * @property {Uuid} objectID The ID of the intersected object. Uuid.NULL for the HUD or invalid intersections. - * @property {number} distance The distance to the intersection point from the origin of the ray. - * @property {Vec3} intersection The intersection point in world-space. - * @property {Vec3} surfaceNormal The surface normal at the intersected point. All NANs if type == INTERSECTED_HUD. - * @property {Variant} extraInfo Additional intersection details when available for Model objects. - * @property {PickRay} searchRay The PickRay that was used. Valid even if there was no intersection. - */ - - /**jsdoc - * An intersection result for a Stylus Pick. - * - * @typedef {object} StylusPickResult - * @property {number} type The intersection type. - * @property {boolean} intersects If there was a valid intersection (type != INTERSECTED_NONE) - * @property {Uuid} objectID The ID of the intersected object. Uuid.NULL for the HUD or invalid intersections. - * @property {number} distance The distance to the intersection point from the origin of the ray. - * @property {Vec3} intersection The intersection point in world-space. - * @property {Vec3} surfaceNormal The surface normal at the intersected point. All NANs if type == INTERSECTED_HUD. - * @property {Variant} extraInfo Additional intersection details when available for Model objects. - * @property {StylusTip} stylusTip The StylusTip that was used. Valid even if there was no intersection. - */ - - /**jsdoc - * An intersection result for a Parabola Pick. - * - * @typedef {object} ParabolaPickResult - * @property {number} type The intersection type. - * @property {boolean} intersects If there was a valid intersection (type != INTERSECTED_NONE) - * @property {Uuid} objectID The ID of the intersected object. Uuid.NULL for the HUD or invalid intersections. - * @property {number} distance The distance to the intersection point from the origin of the parabola, not along the parabola. - * @property {number} parabolicDistance The distance to the intersection point from the origin of the parabola, along the parabola. - * @property {Vec3} intersection The intersection point in world-space. - * @property {Vec3} surfaceNormal The surface normal at the intersected point. All NANs if type == INTERSECTED_HUD. - * @property {Variant} extraInfo Additional intersection details when available for Model objects. - * @property {PickParabola} parabola The PickParabola that was used. Valid even if there was no intersection. - */ - - /**jsdoc - * An intersection result for a Collision Pick. - * - * @typedef {object} CollisionPickResult - * @property {boolean} intersects If there was at least one valid intersection (intersectingObjects.length > 0) - * @property {IntersectingObject[]} intersectingObjects The collision information of each object which intersect with the CollisionRegion. - * @property {CollisionRegion} collisionRegion The CollisionRegion that was used. Valid even if there was no intersection. - */ - - /**jsdoc - * Information about the Collision Pick's intersection with an object - * - * @typedef {object} IntersectingObject - * @property {QUuid} id The ID of the object. - * @property {number} type The type of the object, either Picks.INTERSECTED_ENTITY() or Picks.INTERSECTED_AVATAR() - * @property {CollisionContact[]} collisionContacts Pairs of points representing penetration information between the pick and the object - */ - - /**jsdoc - * A pair of points that represents part of an overlap between a Collision Pick and an object in the physics engine. Points which are further apart represent deeper overlap - * - * @typedef {object} CollisionContact - * @property {Vec3} pointOnPick A point representing a penetration of the object's surface into the volume of the pick, in world space. - * @property {Vec3} pointOnObject A point representing a penetration of the pick's surface into the volume of the found object, in world space. - * @property {Vec3} normalOnPick The normalized vector pointing away from the pick, representing the direction of collision. - */ - - /**jsdoc - * Get the most recent pick result from this Pick. This will be updated as long as the Pick is enabled. + * Gets the most recent result from a pick. A pick continues to be updated ready to return a result, as long as it is + * enabled. + *

Note: Stylus picks only intersect with objects in their include list, set using + * {@link Picks.setIncludeItems|setIncludeItems}.

* @function Picks.getPrevPickResult - * @param {number} uid The ID of the Pick, as returned by {@link Picks.createPick}. - * @returns {RayPickResult|StylusPickResult|ParabolaPickResult|CollisionPickResult} The most recent intersection result. This will be different for different PickTypes. + * @param {number} id - The ID of the pick. + * @returns {RayPickResult|ParabolaPickResult|StylusPickResult|CollisionPickResult} The most recent intersection result. + * @example Highlight entities under your mouse in desktop mode or that you're looking at in HMD mode. + * // Highlight. + * var HIGHLIGHT_LIST_NAME = "highlightEntitiesExampleList"; + * var HIGHLIGHT_LIST_TYPE = "entity"; + * Selection.enableListHighlight(HIGHLIGHT_LIST_NAME, {}); + * + * // Ray pick. + * var PICK_FILTER = Picks.PICK_DOMAIN_ENTITIES | Picks.PICK_AVATAR_ENTITIES + * | Picks.PICK_INCLUDE_COLLIDABLE | Picks.PICK_INCLUDE_NONCOLLIDABLE; + * var rayPick = Picks.createPick(PickType.Ray, { + * enabled: true, + * filter: PICK_FILTER, + * joint: HMD.active ? "Avatar" : "Mouse" + * }); + * + * // Highlight intersected entity. + * var highlightedEntityID = null; + * Script.update.connect(function () { + * var rayPickResult = Picks.getPrevPickResult(rayPick); + * if (rayPickResult.intersects) { + * if (rayPickResult.objectID !== highlightedEntityID) { + * if (highlightedEntityID) { + * Selection.removeFromSelectedItemsList(HIGHLIGHT_LIST_NAME, HIGHLIGHT_LIST_TYPE, highlightedEntityID); + * } + * highlightedEntityID = rayPickResult.objectID; + * Selection.addToSelectedItemsList(HIGHLIGHT_LIST_NAME, HIGHLIGHT_LIST_TYPE, highlightedEntityID); + * } + * } else { + * if (highlightedEntityID) { + * Selection.removeFromSelectedItemsList(HIGHLIGHT_LIST_NAME, HIGHLIGHT_LIST_TYPE, highlightedEntityID); + * highlightedEntityID = null; + * } + * } + * }); + * + * // Clean up. + * Script.scriptEnding.connect(function () { + * if (highlightedEntityID) { + * Selection.removeFromSelectedItemsList(HIGHLIGHT_LIST_NAME, HIGHLIGHT_LIST_TYPE, highlightedEntityID); + * } + * }); */ Q_INVOKABLE QVariantMap getPrevPickResult(unsigned int uid); /**jsdoc - * Sets whether or not to use precision picking. + * Sets whether or not to use precision picking, i.e., whether to 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} uid The ID of the Pick, as returned by {@link Picks.createPick}. - * @param {boolean} precisionPicking Whether or not to use precision picking + * @param {number} id - The ID of the pick. + * @param {boolean} precisionPicking - true to use precision picking, false to use coarse picking. */ Q_INVOKABLE void setPrecisionPicking(unsigned int uid, bool precisionPicking); /**jsdoc - * Sets a list of Entity IDs and/or Avatar IDs to ignore during intersection. Not used by Stylus Picks. + * Sets a list of entity and avatar IDs to ignore during intersection. + *

Note: Not used by stylus picks.

* @function Picks.setIgnoreItems - * @param {number} uid The ID of the Pick, as returned by {@link Picks.createPick}. - * @param {Uuid[]} ignoreItems A list of IDs to ignore. + * @param {number} id - The ID of the pick. + * @param {Uuid[]} ignoreItems - The list of IDs to ignore. */ 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. Stylus - * Picks only intersect with objects in their include list. + * 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.

* @function Picks.setIncludeItems - * @param {number} uid The ID of the Pick, as returned by {@link Picks.createPick}. - * @param {Uuid[]} includeItems A list of IDs to include. + * @param {number} id - The ID of the pick. + * @param {Uuid[]} includeItems - The list of IDs to include. */ Q_INVOKABLE void setIncludeItems(unsigned int uid, const QScriptValue& includeItems); /**jsdoc - * Check if a Pick is associated with the left hand. + * 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. * @function Picks.isLeftHand - * @param {number} uid The ID of the Pick, as returned by {@link Picks.createPick}. - * @returns {boolean} True if the Pick is a Joint Ray or Parabola Pick with joint == "_CONTROLLER_LEFTHAND" or "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", or a Stylus Pick with hand == 0. + * @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. */ Q_INVOKABLE bool isLeftHand(unsigned int uid); /**jsdoc - * Check if a Pick is associated with the right hand. + * 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. * @function Picks.isRightHand - * @param {number} uid The ID of the Pick, as returned by {@link Picks.createPick}. - * @returns {boolean} True if the Pick is a Joint Ray or Parabola Pick with joint == "_CONTROLLER_RIGHTHAND" or "_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND", or a Stylus Pick with hand == 1. + * @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. */ Q_INVOKABLE bool isRightHand(unsigned int uid); /**jsdoc - * Check if a Pick is associated with the system mouse. + * Checks if a pick is associated with the system mouse: a ray or parabola pick with joint set to "Mouse". * @function Picks.isMouse - * @param {number} uid The ID of the Pick, as returned by {@link Picks.createPick}. - * @returns {boolean} True if the Pick is a Mouse Ray or Parabola Pick, false otherwise. + * @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. */ Q_INVOKABLE bool isMouse(unsigned int uid); @@ -261,112 +253,145 @@ public slots: /**jsdoc * @function Picks.PICK_ENTITIES + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int PICK_ENTITIES() { return PickFilter::getBitMask(PickFilter::FlagBit::DOMAIN_ENTITIES) | PickFilter::getBitMask(PickFilter::FlagBit::AVATAR_ENTITIES); } + /**jsdoc * @function Picks.PICK_OVERLAYS + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int PICK_OVERLAYS() { return PickFilter::getBitMask(PickFilter::FlagBit::LOCAL_ENTITIES); } + /**jsdoc * @function Picks.PICK_DOMAIN_ENTITIES + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int PICK_DOMAIN_ENTITIES() { return PickFilter::getBitMask(PickFilter::FlagBit::DOMAIN_ENTITIES); } + /**jsdoc * @function Picks.PICK_AVATAR_ENTITIES + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int PICK_AVATAR_ENTITIES() { return PickFilter::getBitMask(PickFilter::FlagBit::AVATAR_ENTITIES); } + /**jsdoc * @function Picks.PICK_LOCAL_ENTITIES + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int PICK_LOCAL_ENTITIES() { return PickFilter::getBitMask(PickFilter::FlagBit::LOCAL_ENTITIES); } + /**jsdoc * @function Picks.PICK_AVATARS + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int PICK_AVATARS() { return PickFilter::getBitMask(PickFilter::FlagBit::AVATARS); } + /**jsdoc * @function Picks.PICK_HUD + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int PICK_HUD() { return PickFilter::getBitMask(PickFilter::FlagBit::HUD); } + /**jsdoc * @function Picks.PICK_INCLUDE_VISIBLE + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int PICK_INCLUDE_VISIBLE() { return PickFilter::getBitMask(PickFilter::FlagBit::VISIBLE); } + /**jsdoc * @function Picks.PICK_INCLUDE_INVISIBLE + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int PICK_INCLUDE_INVISIBLE() { return PickFilter::getBitMask(PickFilter::FlagBit::INVISIBLE); } + /**jsdoc * @function Picks.PICK_INCLUDE_COLLIDABLE + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int PICK_INCLUDE_COLLIDABLE() { return PickFilter::getBitMask(PickFilter::FlagBit::COLLIDABLE); } + /**jsdoc * @function Picks.PICK_INCLUDE_NONCOLLIDABLE + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int PICK_INCLUDE_NONCOLLIDABLE() { return PickFilter::getBitMask(PickFilter::FlagBit::NONCOLLIDABLE); } + /**jsdoc * @function Picks.PICK_PRECISE + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int PICK_PRECISE() { return PickFilter::getBitMask(PickFilter::FlagBit::PRECISE); } + /**jsdoc * @function Picks.PICK_COARSE + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int PICK_COARSE() { return PickFilter::getBitMask(PickFilter::FlagBit::COARSE); } + /**jsdoc * @function Picks.PICK_ALL_INTERSECTIONS + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int PICK_ALL_INTERSECTIONS() { return PickFilter::getBitMask(PickFilter::FlagBit::PICK_ALL_INTERSECTIONS); } /**jsdoc * @function Picks.INTERSECTED_NONE + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int INTERSECTED_NONE() { return IntersectionType::NONE; } /**jsdoc * @function Picks.INTERSECTED_ENTITY + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int INTERSECTED_ENTITY() { return IntersectionType::ENTITY; } /**jsdoc - * @function Picks.INTERSECTED_OVERLAY + * @function Picks.INTERSECTED_LOCAL_ENTITY + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int INTERSECTED_LOCAL_ENTITY() { return IntersectionType::LOCAL_ENTITY; } /**jsdoc * @function Picks.INTERSECTED_OVERLAY + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int INTERSECTED_OVERLAY() { return INTERSECTED_LOCAL_ENTITY(); } /**jsdoc * @function Picks.INTERSECTED_AVATAR + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int INTERSECTED_AVATAR() { return IntersectionType::AVATAR; } /**jsdoc * @function Picks.INTERSECTED_HUD + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static constexpr unsigned int INTERSECTED_HUD() { return IntersectionType::HUD; } diff --git a/interface/src/raypick/PointerScriptingInterface.h b/interface/src/raypick/PointerScriptingInterface.h index b04d15d888..268b178fb6 100644 --- a/interface/src/raypick/PointerScriptingInterface.h +++ b/interface/src/raypick/PointerScriptingInterface.h @@ -49,7 +49,7 @@ public: * 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 * @function Pointers.createPointer - * @param {PickType} type A PickType that specifies the method of picking to use + * @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. diff --git a/interface/src/raypick/RayPick.h b/interface/src/raypick/RayPick.h index 161c930fef..170a0489da 100644 --- a/interface/src/raypick/RayPick.h +++ b/interface/src/raypick/RayPick.h @@ -39,6 +39,21 @@ public: float distance { FLT_MAX }; bool intersects { false }; + /**jsdoc + * An intersection result for a ray pick. + * + * @typedef {object} RayPickResult + * @property {IntersectionType} type - The intersection type. + * @property {boolean} intersects - true if there's a valid intersection, false if there isn't. + * @property {Uuid} objectID - The ID of the intersected object. null for HUD or invalid intersections. + * @property {number} distance - The distance from the ray origin to the intersection point. + * @property {Vec3} intersection - The intersection point in world coordinates. + * @property {Vec3} surfaceNormal - The surface normal at the intersected point. All NaNs if type == + * Picks.INTERSECTED_HUD. + * @property {SubmeshIntersection} extraInfo - Additional intersection details for model objects, otherwise + * { }. + * @property {PickRay} searchRay - The pick ray that was used. Valid even if there is no intersection. + */ virtual QVariantMap toVariantMap() const override { QVariantMap toReturn; toReturn["type"] = type; diff --git a/interface/src/raypick/RayPickScriptingInterface.h b/interface/src/raypick/RayPickScriptingInterface.h index 64b21ea055..32b2b8fb68 100644 --- a/interface/src/raypick/RayPickScriptingInterface.h +++ b/interface/src/raypick/RayPickScriptingInterface.h @@ -19,29 +19,32 @@ #include "PickScriptingInterface.h" /**jsdoc - * Synonym for {@link Picks} as used for ray picks. Deprecated. + * The RayPick API is a subset of the {@link Picks} API, as used for ray picks. * * @namespace RayPick * + * @deprecated This API is deprecated and will be removed. Use the {@link Picks} API instead. + * * @hifi-interface * @hifi-client-entity * @hifi-avatar * - * @property {number} PICK_ENTITIES Read-only. - * @property {number} PICK_OVERLAYS Read-only. - * @property {number} PICK_AVATARS Read-only. - * @property {number} PICK_HUD Read-only. - * @property {number} PICK_COARSE Read-only. - * @property {number} PICK_INCLUDE_INVISIBLE Read-only. - * @property {number} PICK_INCLUDE_NONCOLLIDABLE Read-only. - * @property {number} PICK_ALL_INTERSECTIONS Read-only. - * @property {number} INTERSECTED_NONE Read-only. - * @property {number} INTERSECTED_ENTITY Read-only. - * @property {number} INTERSECTED_OVERLAY Read-only. - * @property {number} INTERSECTED_AVATAR Read-only. - * @property {number} INTERSECTED_HUD Read-only. + * @property {FilterFlags} PICK_ENTITIES - Include domain and avatar entities when intersecting. + * Read-only. + * @property {FilterFlags} PICK_OVERLAYS - Include local entities when intersecting. Read-only. + * @property {FilterFlags} PICK_AVATARS - Include avatars when intersecting. Read-only. + * @property {FilterFlags} PICK_HUD - Include the HUD sphere when intersecting in HMD mode. Read-only. + * @property {FilterFlags} PICK_PRECISE - Pick against exact meshes. Read-only. + * @property {FilterFlags} PICK_INCLUDE_INVISIBLE - Include invisible objects when intersecting. Read-only. + * @property {FilterFlags} PICK_INCLUDE_NONCOLLIDABLE - Include non-collidable objects when intersecting. Read-only. + * @property {FilterFlags} PICK_ALL_INTERSECTIONS - Return all intersections instead of just the closest. Read-only. + * @property {IntersectionType} INTERSECTED_NONE - Intersected nothing with the given filter flags. Read-only. + * @property {IntersectionType} INTERSECTED_ENTITY - Intersected an entity. Read-only. + * @property {IntersectionType} INTERSECTED_LOCAL_ENTITY - Intersected a local entity. Read-only. + * @property {IntersectionType} INTERSECTED_OVERLAY - Intersected an entity (3D Overlays no longer exist). Read-only. + * @property {IntersectionType} INTERSECTED_AVATAR - Intersected an avatar. Read-only. + * @property {IntersectionType} INTERSECTED_HUD - Intersected the HUD sphere. Read-only. */ - class RayPickScriptingInterface : public QObject, public Dependency { Q_OBJECT Q_PROPERTY(unsigned int PICK_ENTITIES READ PICK_ENTITIES CONSTANT) @@ -63,78 +66,96 @@ class RayPickScriptingInterface : public QObject, public Dependency { public: /**jsdoc + * Creates a new ray pick. + *

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

* @function RayPick.createRayPick - * @param {Picks.RayPickProperties} - * @returns {number} + * @param {Picks.RayPickProperties} properties - Properties of the pick. + * @returns {number} The ID of the pick created. 0 if invalid. */ Q_INVOKABLE unsigned int createRayPick(const QVariant& properties); /**jsdoc + * Enables a ray pick. * @function RayPick.enableRayPick - * @param {number} id + * @param {number} id - The ID of the ray pick. */ Q_INVOKABLE void enableRayPick(unsigned int uid); /**jsdoc + * Disables a ray pick. * @function RayPick.disableRayPick - * @param {number} id + * @param {number} id - The ID of the ray pick. */ Q_INVOKABLE void disableRayPick(unsigned int uid); /**jsdoc + * Removes (deletes) a ray pick. * @function RayPick.removeRayPick - * @param {number} id + * @param {number} id - The ID of the ray pick. */ Q_INVOKABLE void removeRayPick(unsigned int uid); /**jsdoc + * Gets the most recent pick result from a ray pick. A ray pick continues to be updated ready to return a result, as long + * as it is enabled. * @function RayPick.getPrevRayPickResult - * @param {number} id + * @param {number} id - The ID of the ray pick. * @returns {RayPickResult} */ Q_INVOKABLE QVariantMap getPrevRayPickResult(unsigned int uid); /**jsdoc + * Sets whether or not to use precision picking, i.e., whether to pick against precise meshes or coarse meshes. * @function RayPick.setPrecisionPicking - * @param {number} id - * @param {boolean} precisionPicking + * @param {number} id - The ID of the ray pick. + * @param {boolean} precisionPicking - true to use precision picking, false to use coarse picking. */ Q_INVOKABLE void setPrecisionPicking(unsigned int uid, bool precisionPicking); /**jsdoc + * Sets a list of entity and avatar IDs to ignore during intersection. * @function RayPick.setIgnoreItems - * @param {number} id - * @param {Uuid[]) ignoreEntities + * @param {number} id - The ID of the ray pick. + * @param {Uuid[]} ignoreItems - The list of IDs to ignore. */ 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. * @function RayPick.setIncludeItems - * @param {number} id - * @param {Uuid[]) includeEntities + * @param {number} id - The ID of the ray pick. + * @param {Uuid[]} includeItems - The list of IDs to include. */ Q_INVOKABLE void setIncludeItems(unsigned int uid, const QScriptValue& includeEntities); /**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. * @function RayPick.isLeftHand - * @param {number} id - * @returns {boolean} + * @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. */ 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. * @function RayPick.isRightHand - * @param {number} id - * @returns {boolean} + * @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. */ 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". * @function RayPick.isMouse - * @param {number} id - * @returns {boolean} + * @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. */ Q_INVOKABLE bool isMouse(unsigned int uid); @@ -142,84 +163,98 @@ public slots: /**jsdoc * @function RayPick.PICK_ENTITIES + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static unsigned int PICK_ENTITIES() { return PickScriptingInterface::PICK_ENTITIES(); } /**jsdoc * @function RayPick.PICK_OVERLAYS + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static unsigned int PICK_OVERLAYS() { return PickScriptingInterface::PICK_OVERLAYS(); } /**jsdoc * @function RayPick.PICK_AVATARS + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static unsigned int PICK_AVATARS() { return PickScriptingInterface::PICK_AVATARS(); } /**jsdoc * @function RayPick.PICK_HUD + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static unsigned int PICK_HUD() { return PickScriptingInterface::PICK_HUD(); } /**jsdoc * @function RayPick.PICK_COARSE + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static unsigned int PICK_COARSE() { return PickScriptingInterface::PICK_COARSE(); } /**jsdoc * @function RayPick.PICK_INCLUDE_INVISIBLE + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static unsigned int PICK_INCLUDE_INVISIBLE() { return PickScriptingInterface::PICK_INCLUDE_INVISIBLE(); } /**jsdoc * @function RayPick.PICK_INCLUDE_NONCOLLIDABLE + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static unsigned int PICK_INCLUDE_NONCOLLIDABLE() { return PickScriptingInterface::PICK_INCLUDE_NONCOLLIDABLE(); } /**jsdoc * @function RayPick.PICK_ALL_INTERSECTIONS + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static unsigned int PICK_ALL_INTERSECTIONS() { return PickScriptingInterface::PICK_ALL_INTERSECTIONS(); } /**jsdoc * @function RayPick.INTERSECTED_NONE + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static unsigned int INTERSECTED_NONE() { return PickScriptingInterface::INTERSECTED_NONE(); } /**jsdoc * @function RayPick.INTERSECTED_ENTITY + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static unsigned int INTERSECTED_ENTITY() { return PickScriptingInterface::INTERSECTED_ENTITY(); } /**jsdoc * @function RayPick.INTERSECTED_OVERLAY + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static unsigned int INTERSECTED_LOCAL_ENTITY() { return PickScriptingInterface::INTERSECTED_LOCAL_ENTITY(); } /**jsdoc * @function RayPick.INTERSECTED_OVERLAY + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static unsigned int INTERSECTED_OVERLAY() { return PickScriptingInterface::INTERSECTED_LOCAL_ENTITY(); } /**jsdoc * @function RayPick.INTERSECTED_AVATAR + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static unsigned int INTERSECTED_AVATAR() { return PickScriptingInterface::INTERSECTED_AVATAR(); } /**jsdoc * @function RayPick.INTERSECTED_HUD + * @deprecated This function is deprecated and will be removed. Use the property of the same name instead. * @returns {number} */ static unsigned int INTERSECTED_HUD() { return PickScriptingInterface::INTERSECTED_HUD(); } diff --git a/interface/src/raypick/StylusPick.h b/interface/src/raypick/StylusPick.h index 9d5dc10b67..e443fb1c6d 100644 --- a/interface/src/raypick/StylusPick.h +++ b/interface/src/raypick/StylusPick.h @@ -38,6 +38,18 @@ public: glm::vec3 intersection { NAN }; glm::vec3 surfaceNormal { NAN }; + /**jsdoc + * An intersection result for a stylus pick. + * + * @typedef {object} StylusPickResult + * @property {number} type - The intersection type. + * @property {boolean} intersects - true if there's a valid intersection, false if there isn't. + * @property {Uuid} objectID - The ID of the intersected object. null for invalid intersections. + * @property {number} distance - The distance to the intersection point from the stylus tip. + * @property {Vec3} intersection - The intersection point in world coordinates. + * @property {Vec3} surfaceNormal - The surface normal at the intersected point. + * @property {StylusTip} stylusTip - The stylus tip at the time of the result. Valid even if there is no intersection. + */ virtual QVariantMap toVariantMap() const override { QVariantMap toReturn; toReturn["type"] = type; diff --git a/libraries/entities/src/EntityItemProperties.cpp b/libraries/entities/src/EntityItemProperties.cpp index 2b738bc4e7..5d39139b46 100644 --- a/libraries/entities/src/EntityItemProperties.cpp +++ b/libraries/entities/src/EntityItemProperties.cpp @@ -801,7 +801,7 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { * * @property {boolean} collisionless=false - Whether or not the entity should collide with items per its * collisionMask property. If true then the entity does not collide. A synonym is ignoreForCollisions. - * @property {Entities.CollisionMask} collisionMask=31 - What types of items the entity should collide with. + * @property {CollisionMask} collisionMask=31 - What types of items the entity should collide with. * @property {string} collidesWith="static,dynamic,kinematic,myAvatar,otherAvatar," - Synonym for collisionMask, * in text format. * @property {string} collisionSoundURL="" - The sound to play when the entity experiences a collision. Valid file formats are diff --git a/libraries/pointers/src/Pick.h b/libraries/pointers/src/Pick.h index dda35a53a2..1766736664 100644 --- a/libraries/pointers/src/Pick.h +++ b/libraries/pointers/src/Pick.h @@ -20,6 +20,22 @@ #include #include +/**jsdoc + *

The type of an intersection.

+ * + * + * + * + * + * + * + * + * + * + * + *
NameValueDescription
INTERSECTED_NONE0Intersected nothing.
INTERSECTED_ENTITY1Intersected an entity.
INTERSECTED_LOCAL_ENTITY2Intersected a local entity.
INTERSECTED_AVATAR3Intersected an avatar.
INTERSECTED_HUD4Intersected the HUD sphere.
+ * @typedef {number} IntersectionType + */ enum IntersectionType { NONE = 0, ENTITY, @@ -61,7 +77,7 @@ public: virtual ~PickQuery() = default; /**jsdoc - * Enum for different types of Picks and Pointers. + * The PickType API provides constant numeric values that represent different types of picks. * * @namespace PickType * @variation 0 @@ -70,22 +86,28 @@ public: * @hifi-client-entity * @hifi-avatar * - * @property {number} Ray Ray picks intersect a ray with the nearest object in front of them, along a given direction. - * @property {number} Stylus Stylus picks provide "tapping" functionality on/into flat surfaces. - * @property {number} Parabola Parabola picks intersect a parabola with the nearest object in front of them, with a given - * initial velocity and acceleration. - * @property {number} Collision Collision picks intersect a collision volume with avatars and entities that have collisions. + * @property {number} Ray - Ray picks intersect a ray with objects in front of them, along their direction. + * @property {number} Parabola - Parabola picks intersect a parabola with objects in front of them, along their arc. + * @property {number} Stylus - Stylus picks provide "tapping" functionality on or into flat surfaces. + * @property {number} Collision - Collision picks intersect a collision volume with avatars and entities that have + * collisions. */ - /**jsdoc + + /**jsdoc + *

A type of pick.

* * * * * - * - * - * - * + * + * + * + * * *
ValueDescription
{@link PickType(0)|PickType.Ray}
{@link PickType(0)|PickType.Stylus}
{@link PickType(0)|PickType.Parabola}
{@link PickType(0)|PickType.Collision}
{@link PickType(0)|PickType.Ray}Ray picks intersect a ray with objects in front of + * them, along their direction.
{@link PickType(0)|PickType.Parabola}Parabola picks intersect a parabola with objects + * in front of them, along their arc.
{@link PickType(0)|PickType.Stylus}Stylus picks provide "tapping" functionality on or + * into flat surfaces.
{@link PickType(0)|PickType.Collision}Collision picks intersect a collision volume + * with avatars and entities that have collisions.
* @typedef {number} PickType diff --git a/libraries/render-utils/src/Model.cpp b/libraries/render-utils/src/Model.cpp index e2d78a8d94..9d24b8e706 100644 --- a/libraries/render-utils/src/Model.cpp +++ b/libraries/render-utils/src/Model.cpp @@ -445,7 +445,7 @@ bool Model::findRayIntersectionAgainstSubMeshes(const glm::vec3& origin, const g } /**jsdoc - * Information about a submesh intersection point. + * A submesh intersection point. * @typedef {object} SubmeshIntersection * @property {Vec3} worldIntersectionPoint - The intersection point in world coordinates. * @property {Vec3} meshIntersectionPoint - The intersection point in model coordinates. diff --git a/libraries/shared/src/PhysicsCollisionGroups.h b/libraries/shared/src/PhysicsCollisionGroups.h index be641b5cd2..7323133876 100644 --- a/libraries/shared/src/PhysicsCollisionGroups.h +++ b/libraries/shared/src/PhysicsCollisionGroups.h @@ -72,7 +72,7 @@ const int32_t BULLET_COLLISION_MASK_DETAILED_RAY = BULLET_COLLISION_GROUP_DETAIL const int32_t BULLET_COLLISION_MASK_COLLISIONLESS = 0; /**jsdoc - *

An entity may collide with the following types of items:

+ *

A collision may be with the following types of items:

* * * @@ -88,7 +88,7 @@ const int32_t BULLET_COLLISION_MASK_COLLISIONLESS = 0; *
ValueDescription
*

The values for the collision types that are enabled are added together to give the CollisionMask value. For example, a * value of 31 means that an entity will collide with all item types.

- * @typedef {number} Entities.CollisionMask + * @typedef {number} CollisionMask */ // The USER collision groups are exposed to script and can be used to generate per-object collision masks. diff --git a/libraries/shared/src/PickFilter.h b/libraries/shared/src/PickFilter.h index 33f6e7278a..8c1c4f56f6 100644 --- a/libraries/shared/src/PickFilter.h +++ b/libraries/shared/src/PickFilter.h @@ -13,6 +13,34 @@ class PickFilter { public: + + /**jsdoc + *

A set of flags for a pick filter. The value is constructed by using the | (bitwise OR) operator on the + * individual flag values.

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Flag nameValueDescription
PICK_DOMAIN_ENTITIES1Include domain entities when intersecting.
PICK_AVATAR_ENTITIES2Include avatar entities when intersecting.
PICK_LOCAL_ENTITIES4Include local entities when intersecting.
PICK_AVATATRS8Include avatars when intersecting.
PICK_HUD16Include the HUD sphere when intersecting in HMD mode.
PICK_INCLUDE_VISIBLE32Include visible objects when intersecting.
PICK_INCLUDE_INVISIBLE64Include invisible objects when intersecting.
PICK_INCLUDE_COLLIDABLE128Include collidable objects when + * intersecting.
PICK_INCLUDE_NONCOLLIDABLE256Include non-collidable objects when + * intersecting.
PICK_PRECISE512Pick against exact meshes.
PICK_COARSE1024Pick against coarse meshes.
PICK_ALL_INTERSECTIONS2048Return all intersections instead of just the + * closest.
+ * @typedef {number} FilterFlags + */ enum FlagBit { DOMAIN_ENTITIES = 0, AVATAR_ENTITIES, diff --git a/libraries/shared/src/RegisteredMetaTypes.h b/libraries/shared/src/RegisteredMetaTypes.h index d3fb816f3c..ef2d775eec 100644 --- a/libraries/shared/src/RegisteredMetaTypes.h +++ b/libraries/shared/src/RegisteredMetaTypes.h @@ -258,12 +258,12 @@ public: }; /**jsdoc - * A PickRay defines a vector with a starting point. It is used, for example, when finding entities or avatars that lie under a - * mouse click or intersect a laser beam. + * A vector with a starting point. It is used, for example, when finding entities or avatars that lie under a mouse click or + * intersect a laser beam. * * @typedef {object} PickRay - * @property {Vec3} origin - The starting position of the PickRay. - * @property {Vec3} direction - The direction that the PickRay travels. + * @property {Vec3} origin - The starting position of the ray. + * @property {Vec3} direction - The direction that the ray travels. */ class PickRay : public MathPick { public: @@ -291,13 +291,14 @@ QScriptValue pickRayToScriptValue(QScriptEngine* engine, const PickRay& pickRay) void pickRayFromScriptValue(const QScriptValue& object, PickRay& pickRay); /**jsdoc - * A StylusTip defines the tip of a stylus. + * The tip of a stylus. * * @typedef {object} StylusTip - * @property {number} side - The hand the tip is attached to: 0 for left, 1 for right. - * @property {Vec3} tipOffset - the position offset of the stylus tip. + * @property {number} side - The hand that the stylus is attached to: 0 for left hand, 1 for the + * right hand, -1 for invalid. + * @property {Vec3} tipOffset - The position of the stylus tip relative to the body of the stylus. * @property {Vec3} position - The position of the stylus tip. - * @property {Quat} orientation - The orientation of the stylus tip. + * @property {Quat} orientation - The orientation of the stylus. * @property {Vec3} velocity - The velocity of the stylus tip. */ class StylusTip : public MathPick { @@ -333,12 +334,16 @@ public: }; /**jsdoc -* A PickParabola defines a parabola with a starting point, intitial velocity, and acceleration. +* A parabola defined by a starting point, initial velocity, and acceleration. It is used, for example, when finding entities or +* avatars that intersect a parabolic beam. * * @typedef {object} PickParabola -* @property {Vec3} origin - The starting position of the PickParabola. -* @property {Vec3} velocity - The starting velocity of the parabola. -* @property {Vec3} acceleration - The acceleration that the parabola experiences. +* @property {Vec3} origin - The starting position of the parabola, i.e., the initial position of a virtual projectile whose +* trajectory defines the parabola. +* @property {Vec3} velocity - The starting velocity of the parabola in m/s, i.e., the initial speed of a virtual projectile +* whose trajectory defines the parabola. +* @property {Vec3} acceleration - The acceleration that the parabola experiences in m/s2, i.e., the acceleration of +* a virtual projectile whose trajectory defines the parabola, both magnitude and direction. */ class PickParabola : public MathPick { public: @@ -364,23 +369,6 @@ public: } }; -// TODO: Add "loaded" to CollisionRegion jsdoc once model collision picks are supported. - -/**jsdoc -* A CollisionRegion defines a volume for checking collisions in the physics simulation. - -* @typedef {object} CollisionRegion -* @property {Shape} shape - The information about the collision region's size and shape. Dimensions are in world space, but will scale with the parent if defined. -* @property {Vec3} position - The position of the collision region, relative to a parent if defined. -* @property {Quat} orientation - The orientation of the collision region, relative to a parent if defined. -* @property {float} threshold - The approximate minimum penetration depth for a test object to be considered in contact with the collision region. -* The depth is measured in world space, but will scale with the parent if defined. -* @property {CollisionMask} [collisionGroup=8] - The type of object this collision pick collides as. Objects whose collision masks overlap with the pick's collision group -* will be considered colliding with the pick. -* @property {Uuid} parentID - The ID of the parent, either an avatar or an entity. -* @property {number} parentJointIndex - The joint of the parent to parent to, for example, the joints on the model of an avatar. (default = 0, no joint) -* @property {string} joint - If "Mouse," parents the pick to the mouse. If "Avatar," parents the pick to MyAvatar's head. Otherwise, parents to the joint of the given name on MyAvatar. -*/ class CollisionRegion : public MathPick { public: CollisionRegion() { } @@ -435,6 +423,29 @@ public: } } + /**jsdoc + * A volume for checking collisions in the physics simulation. + * @typedef {object} CollisionRegion + * @property {Shape} shape - The collision region's shape and size. Dimensions are in world space, but scale with the parent + * if defined. + * @property {boolean} loaded - true if the shape has no model, or has a model and it is loaded. + * @property {Vec3} position - The position of the collision region, relative to the parent if defined. + * @property {Quat} orientation - The orientation of the collision region, relative to the parent if defined. + * @property {number} threshold - The approximate minimum penetration depth for a test object to be considered in contact with + * the collision region. The depth is in world coordinates but scales with the parent if defined. + * @property {CollisionMask} [collisionGroup=8] - The type of objects the collision region collides as. Objects whose collision + * masks overlap with the regions's collision group are considered to be colliding with the region. + */ + + /**jsdoc + * A physical volume. + * @typedef {object} Shape + * @property {ShapeType} shapeType="none" - The type of shape. + * @property {string} [modelUrl=""] - The model to load to for the shape if shapeType is one of + * "compound", "simple-hull", "simple-compound", or "static-mesh". + * @property {Vec3} dimensions - The dimensions of the shape. + */ + QVariantMap toVariantMap() const override { QVariantMap collisionRegion; @@ -589,7 +600,7 @@ namespace std { } /**jsdoc - *

The type of a collision contact event. + *

The type of a collision contact event.

* * * diff --git a/libraries/shared/src/ShapeInfo.cpp b/libraries/shared/src/ShapeInfo.cpp index bf51e455c5..33e4bc7095 100644 --- a/libraries/shared/src/ShapeInfo.cpp +++ b/libraries/shared/src/ShapeInfo.cpp @@ -39,6 +39,8 @@ * sub-meshes. * * + * + * * * *
ValueDescription
"static-mesh"The exact shape of the model.
"plane"A plane.
"ellipsoid"An ellipsoid.
"circle"A circle.
"multisphere"A convex hull generated from a set of spheres.