History

Picks, PickType, RayPick JSDoc update

David Rowe committed 7 years ago

Commit 73fd61d1 parent 404be4215 files · +512 −267Browse files

Showing the changes to interface/src/raypick/PickScriptingInterface.cpp (1 of 15 files). Show all

Unified · Split

interface/src/raypick/PickScriptingInterface.cpp+107−60
@@ -55,23 +55,37 @@ PickFilter getPickFilter(unsigned int filter) { · 54 unmodified lines
5555 }
5656
5757 /**jsdoc
58− * A set of properties that can be passed to {@link Picks.createPick} to create a new Ray Pick.
58+ * A set of properties that can be passed to {@link Picks.createPick} when creating a new ray pick.
59+ *
5960 * @typedef {object} Picks.RayPickProperties
60− * @property {boolean} [enabled=false] If this Pick should start enabled or not. Disabled Picks do not updated their pick results.
61− * @property {number} [filter=0] The filter for this Pick to use, constructed using filter flags combined using bitwise OR.
62− * @property {number} [maxDistance=0.0] The max distance at which this Pick will intersect. 0.0 = no max. < 0.0 is invalid.
63− * @property {Uuid} parentID - The ID of the parent, either an avatar, an entity, or a pick.
64− * @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)
65− * @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.
66− * @property {Vec3} [posOffset=Vec3.ZERO] Only for Joint Ray Picks. A local joint position offset, in meters. x = upward, y = forward, z = lateral
67− * @property {Vec3} [dirOffset=Vec3.UP] Only for Joint Ray Picks. A local joint direction offset. x = upward, y = forward, z = lateral
68− * @property {Vec3} [position] Only for Static Ray Picks. The world-space origin of the ray.
69− * @property {Vec3} [direction=-Vec3.UP] Only for Static Ray Picks. The world-space direction of the ray.
61+ * @property {boolean} [enabled=false] - <code>true</code> if this pick should start enabled, <code>false</code> if it should
62+ * start disabled. Disabled picks do not update their pick results.
63+ * @property {FilterFlags} [filter=0] - The filter for this pick to use. Construct using {@link Picks} FilterFlags property
64+ * values (e.g., <code>Picks.PICK_DOMAIN_ENTTITIES</code>) combined with <code>|</code> (bitwise OR) operators.
65+ * @property {number} [maxDistance=0.0] - The maximum distance at which this pick will intersect. A value of <code>0.0</code>
66+ * means no maximum.
67+ * @property {Uuid} [parentID] - The ID of the parent: either an avatar, an entity, or another pick.
68+ * @property {number} [parentJointIndex=0] - The joint of the parent to parent to, for example, an avatar joint.
69+ * A value of <code>0</code> means no joint.<br />
70+ * <em>Used only if <code>parentID</code> is specified.</em>
71+ * @property {string} [joint] - <code>"Mouse"</code> parents the pick to the mouse; <code>"Avatar"</code> parents the pick to
72+ * the user's avatar head; a joint name parents to the joint in the user's avatar; otherwise the pick is "static", not
73+ * parented to anything.<br />
74+ * <em>Used only if <code>parentID</code> is not specified.</em>
75+ * @property {Vec3} [position=Vec3.ZERO] - The offset of the ray origin from its parent if parented, otherwise the ray origin
76+ * in world coordinates.
77+ * @property {Vec3} [posOffset] - Synonym for <code>position</code>.
78+ * @property {Vec3} [direction] - The offset of the ray direction from its parent's y-axis if parented, otherwise the ray
79+ * direction in world coordinates.
80+ * <p><strong>Default Value:</strong> <code>Vec3.UP</code> direction if <code>joint</code> is specified, otherwise
81+ * <code>-Vec3.UP</code>.</p>
82+ * @property {Vec3} [dirOffset] - Synonym for <code>direction</code>.
83+ * @property {Quat} [orientation] - Alternative property for specifying <code>direction</code>. The value is applied to the
84+ * default <code>direction</code> value.
7085 */
7186 unsigned int PickScriptingInterface::createRayPick(const QVariant& properties) {
7287 QVariantMap propMap = properties.toMap();
7388
74−
7589 #if defined (Q_OS_ANDROID)
7690 QString jointName { "" };
7791 if (propMap["joint"].isValid()) {
@@ -124,12 +138,20 @@ unsigned int PickScriptingInterface::createRayPick(const QVariant& properties) { · 46 unmodified lines
124138 }
125139
126140 /**jsdoc
127− * A set of properties that can be passed to {@link Picks.createPick} to create a new Stylus Pick.
141+ * A set of properties that can be passed to {@link Picks.createPick} when creating a new stylus pick.
142+ *
128143 * @typedef {object} Picks.StylusPickProperties
129− * @property {number} [hand=-1] An integer. 0 == left, 1 == right. Invalid otherwise.
130− * @property {boolean} [enabled=false] If this Pick should start enabled or not. Disabled Picks do not updated their pick results.
131− * @property {number} [filter=0] The filter for this Pick to use, constructed using filter flags combined using bitwise OR.
132− * @property {number} [maxDistance=0.0] The max distance at which this Pick will intersect. 0.0 = no max. < 0.0 is invalid.
144+ * @property {number} [hand=-1] <code>0</code> for the left hand, <code>1</code> for the right hand, invalid (<code>-1</code>)
145+ * otherwise.
146+ * @property {boolean} [enabled=false] - <code>true</code> if this pick should start enabled, <code>false</code> if it should
147+ * start disabled. Disabled picks do not update their pick results.
148+ * @property {number} [filter=0] - The filter for this pick to use. Construct using {@link Picks} FilterFlags property
149+ * values (e.g., <code>Picks.PICK_DOMAIN_ENTTITIES</code>) combined with <code>|</code> (bitwise OR) operators.
150+ * <p><strong>Note:</strong> Stylus picks do not intersect avatars or the HUD.</p>
151+ * @property {number} [maxDistance=0.0] - The maximum distance at which this pick will intersect. A value of <code>0.0</code>
152+ * means no maximum.
153+ * @property {Vec3} [tipOffset=0,0.095,0] - The position of the stylus tip relative to the hand position at default avatar
154+ * scale.
133155 */
134156 unsigned int PickScriptingInterface::createStylusPick(const QVariant& properties) {
135157 QVariantMap propMap = properties.toMap();
@@ -167,23 +189,45 @@ unsigned int PickScriptingInterface::createStylusPick(const QVariant& properties · 31 unmodified lines
167189
168190 // NOTE: Laser pointer still uses scaleWithAvatar. Until scaleWithAvatar is also deprecated for pointers, scaleWithAvatar should not be removed from the pick API.
169191 /**jsdoc
170− * A set of properties that can be passed to {@link Picks.createPick} to create a new Parabola Pick.
192+ * A set of properties that can be passed to {@link Picks.createPick} when creating a new parabola pick.
193+ *
171194 * @typedef {object} Picks.ParabolaPickProperties
172− * @property {boolean} [enabled=false] If this Pick should start enabled or not. Disabled Picks do not updated their pick results.
173− * @property {number} [filter=0] The filter for this Pick to use, constructed using filter flags combined using bitwise OR.
174− * @property {number} [maxDistance=0.0] The max distance at which this Pick will intersect. 0.0 = no max. < 0.0 is invalid.
175− * @property {Uuid} parentID - The ID of the parent, either an avatar, an entity, or a pick.
176− * @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)
177− * @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.
178− * @property {Vec3} [posOffset=Vec3.ZERO] Only for Joint Parabola Picks. A local joint position offset, in meters. x = upward, y = forward, z = lateral
179− * @property {Vec3} [dirOffset=Vec3.UP] Only for Joint Parabola Picks. A local joint direction offset. x = upward, y = forward, z = lateral
180− * @property {Vec3} [position] Only for Static Parabola Picks. The world-space origin of the parabola segment.
181− * @property {Vec3} [direction=-Vec3.FRONT] Only for Static Parabola Picks. The world-space direction of the parabola segment.
182− * @property {number} [speed=1] The initial speed of the parabola, i.e. the initial speed of the projectile whose trajectory defines the parabola.
183− * @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.
184− * @property {boolean} [rotateAccelerationWithAvatar=true] Whether or not the acceleration axis should rotate with the avatar's local Y axis.
185− * @property {boolean} [rotateAccelerationWithParent=false] Whether or not the acceleration axis should rotate with the parent's local Y axis, if available.
186− * @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.
195+ * @property {boolean} [enabled=false] - <code>true</code> if this pick should start enabled, <code>false</code> if it should
196+ * start disabled. Disabled picks do not update their pick results.
197+ * @property {number} [filter=0] - The filter for this pick to use. Construct using {@link Picks} FilterFlags property
198+ * values (e.g., <code>Picks.PICK_DOMAIN_ENTTITIES</code>) combined with <code>|</code> (bitwise OR) operators.
199+ * @property {number} [maxDistance=0.0] - The maximum distance at which this pick will intersect. A value of <code>0.0</code>
200+ * means no maximum.
201+ * @property {Uuid} [parentID] - The ID of the parent: either an avatar, an entity, or another pick.
202+ * @property {number} [parentJointIndex=0] - The joint of the parent to parent to, for example, an avatar joint.
203+ * A value of <code>0</code> means no joint.<br />
204+ * <em>Used only if <code>parentID</code> is specified.</em>
205+ * @property {string} [joint] - <code>"Mouse"</code> parents the pick to the mouse; <code>"Avatar"</code> parents the pick to
206+ * the user's avatar head; a joint name parents to the joint in the user's avatar; otherwise the pick is "static", not
207+ * parented to anything.
208+ * <em>Used only if <code>parentID</code> is not specified.</em>
209+ * @property {Vec3} [position=Vec3.ZERO] - The offset of the parabola origin from its parent if parented, otherwise the
210+ * parabola origin in world coordinates.
211+ * @property {Vec3} [posOffset] - Synonym for <code>position</code>.
212+ * @property {Vec3} [direction] - The offset of the parabola direction from its parent's y-axis if parented, otherwise the
213+ * parabola direction in world coordinates.
214+ * <p><strong>Default Value:</strong> <code>Vec3.UP</code> direction if <code>joint</code> is specified, otherwise
215+ * <code>Vec3.FRONT</code>.</p>
216+ * @property {Vec3} [dirOffset] - Synonym for <code>direction</code>.
217+ * @property {Quat} [orientation] - Alternative property for specifying <code>direction</code>. The value is applied to the
218+ * default <code>direction</code> value.
219+ * @property {number} [speed=1] - The initial speed of the parabola in m/s, i.e., the initial speed of a virtual projectile
220+ * whose trajectory defines the parabola.
221+ * @property {Vec3} [accelerationAxis=-Vec3.UP] - The acceleration of the parabola in m/s<sup>2</sup>, i.e., the acceleration
222+ * of a virtual projectile whose trajectory defines the parabola, both magnitude and direction.
223+ * @property {boolean} [rotateAccelerationWithAvatar=true] - <code>true</code> if the acceleration axis should rotate with the
224+ * avatar about the avatar's y-axis, <code>false</code> if it shouldn't.
225+ * @property {boolean} [rotateAccelerationWithParent=false] - <code>true</code> if the acceleration axis should rotate with the
226+ * parent about the parent's y-axis, if available.
227+ * @property {boolean} [scaleWithParent=true] - <code>true</code> if the velocity and acceleration of the pick should scale
228+ * with the avatar or other parent.
229+ * @property {boolean} [scaleWithAvatar=true] - Synonym for <code>scalewithParent</code>.
230+ * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
187231 */
188232 unsigned int PickScriptingInterface::createParabolaPick(const QVariant& properties) {
189233 QVariantMap propMap = properties.toMap();
@@ -251,35 +295,38 @@ unsigned int PickScriptingInterface::createParabolaPick(const QVariant& properti · 61 unmodified lines
251295 return DependencyManager::get<PickManager>()->addPick(PickQuery::Parabola, parabolaPick);
252296 }
253297
254−/**jsdoc
255−* A Shape defines a physical volume.
256−*
257−* @typedef {object} Shape
258−* @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"
259−* @property {Vec3} dimensions - The size to scale the shape to.
260−*/
261−
262−// TODO: Add this property to the Shape jsdoc above once model picks work properly
263−// * @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.
264298
265299 /**jsdoc
266−* A set of properties that can be passed to {@link Picks.createPick} to create a new Collision Pick.
267−
268−* @typedef {object} Picks.CollisionPickProperties
269−* @property {boolean} [enabled=false] If this Pick should start enabled or not. Disabled Picks do not updated their pick results.
270−* @property {number} [filter=0] The filter for this Pick to use, constructed using filter flags combined using bitwise OR.
271−* @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.
272−* @property {Vec3} position - The position of the collision region, relative to a parent if defined.
273−* @property {Quat} orientation - The orientation of the collision region, relative to a parent if defined.
274−* @property {float} threshold - The approximate minimum penetration depth for a test object to be considered in contact with the collision region.
275−* The depth is measured in world space, but will scale with the parent if defined.
276−* @property {CollisionMask} [collisionGroup=8] - The type of object this collision pick collides as. Objects whose collision masks overlap with the pick's collision group
277−* will be considered colliding with the pick.
278−* @property {Uuid} parentID - The ID of the parent, either an avatar, an entity, or a pick.
279−* @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)
280−* @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.
281−* @property {boolean} [scaleWithParent=true] If true, the collision pick's dimensions and threshold will adjust according to the scale of the parent.
282−*/
300+ * A set of properties that can be passed to {@link Picks.createPick} when creating a new collision pick.
301+ *
302+ * @typedef {object} Picks.CollisionPickProperties
303+ * @property {boolean} [enabled=false] - <code>true</code> if this pick should start enabled, <code>false</code> if it should
304+ * start disabled. Disabled picks do not update their pick results.
305+ * @property {FilterFlags} [filter=0] - The filter for this pick to use. Construct using {@link Picks} FilterFlags property
306+ * values (e.g., <code>Picks.PICK_DOMAIN_ENTTITIES</code>) combined with <code>|</code> (bitwise OR) operators.
307+ * <p><strong>Note:</strong> Collision picks do not intersect the HUD.</p>
308+ * @property {number} [maxDistance=0.0] - The maximum distance at which this pick will intersect. A value of <code>0.0</code>
309+ * means no maximum.
310+ * @property {Uuid} [parentID] - The ID of the parent: either an avatar, an entity, or another pick.
311+ * @property {number} [parentJointIndex=0] - The joint of the parent to parent to, for example, an avatar joint.
312+ * A value of <code>0</code> means no joint.<br />
313+ * <em>Used only if <code>parentID</code> is specified.</em>
314+ * @property {string} [joint] - <code>"Mouse"</code> parents the pick to the mouse; <code>"Avatar"</code> parents the pick to
315+ * the user's avatar head; a joint name parents to the joint in the user's avatar; otherwise the pick is "static", not
316+ * parented to anything.<br />
317+ * <em>Used only if <code>parentID</code> is not specified.</em>
318+ * @property {boolean} [scaleWithParent=true] - <code>true</code> to scale the pick's dimensions and threshold according to the
319+ * scale of the parent.
320+ *
321+ * @property {Shape} shape - The collision region's shape and size. Dimensions are in world coordinates but scale with the
322+ * parent if defined.
323+ * @property {Vec3} position - The position of the collision region, relative to the parent if defined.
324+ * @property {Quat} orientation - The orientation of the collision region, relative to the parent if defined.
325+ * @property {number} threshold - The approximate minimum penetration depth for a test object to be considered in contact with
326+ * the collision region. The depth is in world coordinates but scales with the parent if defined.
327+ * @property {CollisionMask} [collisionGroup=8] - The type of objects the collision region collides as. Objects whose collision
328+ * masks overlap with the regions's collision group are considered to be colliding with the region.
329+ */
283330 unsigned int PickScriptingInterface::createCollisionPick(const QVariant& properties) {
284331 QVariantMap propMap = properties.toMap();
285332