History

Revise Pointers API JSDoc

David Rowe committed 7 years ago

Commit f2cf3bd1 parent 043aee42 files · +467 −180Browse files

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

Unified · Split

interface/src/raypick/PointerScriptingInterface.cpp+152−98
@@ -51,21 +51,21 @@ unsigned int PointerScriptingInterface::createPointer(const PickQuery::PickType& · 50 unmodified lines
5151 }
5252
5353 /**jsdoc
54− * 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.
54+ * The properties of a stylus pointer. These include the properties from the underlying stylus pick that the pointer uses.
5555 * @typedef {object} Pointers.StylusPointerProperties
56− * @property {boolean} [hover=false] If this pointer should generate hover events.
57− * @property {boolean} [enabled=false]
58− * @property {Vec3} [tipOffset] The specified offset of the from the joint index.
59− * @property {Pointers.StylusPointerProperties.model} [model] Data to replace the default model url, positionOffset and rotationOffset.
56+ * @property {Pointers.StylusPointerModel} [model] - Override some or all of the default stylus model properties.
57+ * @property {boolean} [hover=false] - If <code>true</code>, the pointer generates {@link Entities} hover events.
58+ * @see {@link Picks.StylusPickProperties} for additional properties from the underlying stylus pick.
59+ */
60+/**jsdoc
61+ * The properties of a stylus pointer model.
62+ * @typedef {object} Pointers.StylusPointerModel
63+ * @property {string} [url] - The url of a model to use for the stylus, to override the default stylus mode.
64+ * @property {Vec3} [dimensions] - The dimensions of the stylus, to override the default stylus dimensions.
65+ * @property {Vec3} [positionOffset] - The position offset of the model from the stylus tip, to override the default position
66+ * offset.
67+ * @property {Quat} [rotationOffset] - The rotation offset of the model from the hand, to override the default rotation offset.
6068 */
61− /**jsdoc
62− * properties defining stylus pick model that can be included to {@link Pointers.StylusPointerProperties}
63− * @typedef {object} Pointers.StylusPointerProperties.model
64− * @property {string} [url] url to the model
65− * @property {Vec3} [dimensions] the dimensions of the model
66− * @property {Vec3} [positionOffset] the position offset of the model from the stylus tip.
67− * @property {Vec3} [rotationOffset] the rotation offset of the model from the parent joint index
68− */
6969 unsigned int PointerScriptingInterface::createStylus(const QVariant& properties) const {
7070 QVariantMap propertyMap = properties.toMap();
7171
@@ -104,48 +104,76 @@ unsigned int PointerScriptingInterface::createStylus(const QVariant& properties) · 32 unmodified lines
104104 }
105105
106106 /**jsdoc
107− * 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},
108− * but with an additional distance field.
109− *
107+ * Properties that define the visual appearance of a ray pointer when the pointer is not intersecting something. These are the
108+ * properties of {@link Pointers.RayPointerRenderState} but with an additional property.
110109 * @typedef {object} Pointers.DefaultRayPointerRenderState
111− * @augments Pointers.RayPointerRenderState
112− * @property {number} distance The distance at which to render the end of this Ray Pointer, if one is defined.
110+ * @property {number} distance - The distance at which to render the end of the ray pointer.
111+ * @see {@link Pointers.RayPointerRenderState} for the remainder of the properties.
113112 */
114113 /**jsdoc
115− * A set of properties which define the visual aspect of a Ray Pointer in the case that the Pointer is intersecting something.
116− *
114+ * Properties that define the visual appearance of a ray pointer when the pointer is intersecting something.
117115 * @typedef {object} Pointers.RayPointerRenderState
118− * @property {string} name When using {@link Pointers.createPointer}, the name of this render state, used by {@link Pointers.setRenderState} and {@link Pointers.editRenderState}
119− * @property {Overlays.OverlayProperties|QUuid} [start] When using {@link Pointers.createPointer}, an optionally defined object to represent the beginning of the Ray Pointer,
120− * using the properties you would normally pass to {@link Overlays.addOverlay}, plus the type (as a <code>type</code> field).
121− * When returned from {@link Pointers.getPointerProperties}, the ID of the created object if it exists, or a null ID otherwise.
122− * @property {Overlays.OverlayProperties|QUuid} [path] When using {@link Pointers.createPointer}, an optionally defined object to represent the path of the Ray Pointer,
123− * using the properties you would normally pass to {@link Overlays.addOverlay}, plus the type (as a <code>type</code> field), which <b>must</b> be <code>"line3d"</code>.
124− * When returned from {@link Pointers.getPointerProperties}, the ID of the created object if it exists, or a null ID otherwise.
125− * @property {Overlays.OverlayProperties|QUuid} [end] When using {@link Pointers.createPointer}, an optionally defined object to represent the end of the Ray Pointer,
126− * using the properties you would normally pass to {@link Overlays.addOverlay}, plus the type (as a <code>type</code> field).
127− * When returned from {@link Pointers.getPointerProperties}, the ID of the created object if it exists, or a null ID otherwise.
116+ * @property {string} name - When creating using {@link Pointers.createPointer}, the name of the render state.
117+ * @property {Overlays.OverlayProperties|Uuid} [start]
118+ * <p>When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of
119+ * an overlay to render at the start of the ray pointer. The <code>type</code> property must be specified.</p>
120+ * <p>When getting using {@link Pointers.getPointerProperties}, the ID of the overlay rendered at the start of the ray;
121+ * <code>null</code> if there is no overlay.
122+ *
123+ * @property {Overlays.OverlayProperties|Uuid} [path]
124+ * <p>When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of
125+ * the overlay rendered for the path of the ray pointer. The <code>type</code> property must be specified and be
126+ * <code>"line3d"</code>.</p>
127+ * <p>When getting using {@link Pointers.getPointerProperties}, the ID of the overlay rendered for the path of the ray;
128+ * <code>null</code> if there is no overlay.
129+ *
130+ * @property {Overlays.OverlayProperties|Uuid} [end]
131+ * <p>When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of
132+ * an overlay to render at the end of the ray pointer. The <code>type</code> property must be specified.</p>
133+ * <p>When getting using {@link Pointers.getPointerProperties}, the ID of the overlay rendered at the end of the ray;
134+ * <code>null</code> if there is no overlay.
128135 */
129136 /**jsdoc
130− * 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.
131− * @typedef {object} Pointers.LaserPointerProperties
132− * @property {boolean} [faceAvatar=false] If true, the end of the Pointer will always rotate to face the avatar.
133− * @property {boolean} [centerEndY=true] If false, the end of the Pointer will be moved up by half of its height.
134− * @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.
135− * @property {boolean} [distanceScaleEnd=false] If true, the dimensions of the end of the Pointer will scale linearly with distance.
136− * @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.
137− * @property {boolean} [followNormal=false] If true, the end of the Pointer will rotate to follow the normal of the intersected surface.
138− * @property {number} [followNormalStrength=0.0] The strength of the interpolation between the real normal and the visual normal if followNormal is true. <code>0-1</code>. If 0 or 1,
139− * the normal will follow exactly.
140− * @property {boolean} [enabled=false]
141− * @property {Pointers.RayPointerRenderState[]|Object.<string, Pointers.RayPointerRenderState>} [renderStates] A collection of different visual states to switch between.
142− * When using {@link Pointers.createPointer}, a list of RayPointerRenderStates.
143− * When returned from {@link Pointers.getPointerProperties}, a map between render state names and RayPointRenderStates.
144− * @property {Pointers.DefaultRayPointerRenderState[]|Object.<string, Pointers.DefaultRayPointerRenderState>} [defaultRenderStates] A collection of different visual states to use if there is no intersection.
145− * When using {@link Pointers.createPointer}, a list of DefaultRayPointerRenderStates.
146− * When returned from {@link Pointers.getPointerProperties}, a map between render state names and DefaultRayPointRenderStates.
147− * @property {boolean} [hover=false] If this Pointer should generate hover events.
148− * @property {Pointers.Trigger[]} [triggers] A list of different triggers mechanisms that control this Pointer's click event generation.
137+ * The properties of a ray pointer. These include the properties from the underlying ray pick that the pointer uses.
138+ * @typedef {object} Pointers.RayPointerProperties
139+ * @property {boolean} [faceAvatar=false] - <code>true</code> if the overlay rendered at the end of the ray rotates about the
140+ * world y-axis to always face the avatar; <code>false</code> if it maintains its world orientation.
141+ * @property {boolean} [centerEndY=true] - <code>true</code> if the overlay rendered at the end of the ray is centered on
142+ * the ray end; <code>false</code> if the overlay is rendered adjacent to the surface if <code>followNormal</code> is
143+ * <code>true</code> or on top of the ray end if if <code>followNormal</code> is <code>false</code>.
144+* @property {boolean} [lockEnd=false] - <code>true</code> if the end of the ray is locked to the center of the object at
145+ * which the ray is pointing; <code>false</code> if the end of the ray is at the intersected surface.
146+ * @property {boolean} [distanceScaleEnd=false] - <code>true</code> if the dimensions of the overlay at the end of the ray
147+ * scale linearly with distance; <code>false</code> if they aren't.
148+ * @property {boolean} [scaleWithParent=false] - <code>true</code> if the width of the ray's path and the size of the
149+ * start and end overlays scale linearly with the pointer parent's scale; <code>false</code> if they don't scale.
150+ * @property {boolean} [scaleWithAvatar=false] - A synonym for <code>scalewithParent</code>.
151+ * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
152+ * @property {boolean} [followNormal=false] - <code>true</code> if the overlay rendered at the end of the ray rotates to
153+ * follow the normal of the surface if one is intersected; <code>false</code> if it doesn't.
154+ * @property {number} [followNormalStrength=0.0] - How quickly the overlay rendered at the end of the ray rotates to follow
155+ * the normal of an intersected surface. If <code>0</code> or <code>1</code>, the overlay rotation follows instantaneously;
156+ * for other values, the larger the value the more quickly the rotation follows.
157+ * @property {Pointers.RayPointerRenderState[]|Object.<string, Pointers.RayPointerRenderState>} [renderStates]
158+ * <p>A set of visual states that can be switched among using {@link Pointers.setRenderState}. These define the visual
159+ * appearance of the pointer when it is intersecting something.</p>
160+ * <p>When setting using {@link Pointers.createPointer}, an array of
161+ * {@link Pointers.RayPointerRenderState|RayPointerRenderState} values.</p>
162+ * <p>When getting using {@link Pointers.getPointerProperties}, an object mapping render state names to
163+ * {@link Pointers.RayPointerRenderState|RayPointerRenderState} values.</p>
164+ * @property {Pointers.DefaultRayPointerRenderState[]|Object.<string, Pointers.DefaultRayPointerRenderState>}
165+ * [defaultRenderStates]
166+ * <p>A set of visual states that can be switched among using {@link Pointers.setRenderState}. These define the visual
167+ * appearance of the pointer when it is not intersecting something.</p>
168+ * <p>When setting using {@link Pointers.createPointer}, an array of
169+ * {@link Pointers.DefaultRayPointerRenderState|DefaultRayPointerRenderState} values.</p>
170+ * <p>When getting using {@link Pointers.getPointerProperties}, an object mapping render state names to
171+ * {@link Pointers.DefaultRayPointerRenderState|DefaultRayPointerRenderState} values.</p>
172+ * @property {boolean} [hover=false] - <code>true</code> if the pointer generates {@link Entities} hover events,
173+ * <code>false</code> if it doesn't.
174+ * @property {Pointers.Trigger[]} [triggers=[]] - A list of ways that a {@link Controller} action or function should trigger
175+ * events on the entity or overlay currently intersected.
176+ * @see {@link Picks.RayPickProperties} for additional properties from the underlying ray pick.
149177 */
150178 unsigned int PointerScriptingInterface::createLaserPointer(const QVariant& properties) const {
151179 QVariantMap propertyMap = properties.toMap();
@@ -260,58 +288,84 @@ unsigned int PointerScriptingInterface::createLaserPointer(const QVariant& prope · 108 unmodified lines
260288 }
261289
262290 /**jsdoc
263−* The rendering properties of the parabolic path
264−*
265−* @typedef {object} Pointers.ParabolaProperties
266−* @property {Color} color=255,255,255 The color of the parabola.
267−* @property {number} alpha=1.0 The alpha of the parabola.
268−* @property {number} width=0.01 The width of the parabola, in meters.
269−* @property {boolean} isVisibleInSecondaryCamera=false The width of the parabola, in meters.
270−* @property {boolean} drawInFront=false If <code>true</code>, the parabola is rendered in front of other items in the scene.
271−*/
291+ * The visual appearance of the parabolic path.
292+ * @typedef {object} Pointers.ParabolaPointerPath
293+ * @property {Color} [color=255,255,255] - The color of the parabola.
294+ * @property {number} [alpha=1.0] - The opacity of the parabola, range <code>0.0</code> &ndash; <code>1.0</code>.
295+ * @property {number} [width=0.01] - The width of the parabola, in meters.
296+ * @property {boolean} [isVisibleInSecondaryCamera=false] - <code>true</code> if the parabola is rendered in the secondary
297+ * camera, <code>false</code> if it isn't.
298+ * @property {boolean} [drawInFront=false] - <code>true</code> if the parabola is rendered in front of objects in the world,
299+ * but behind the HUD, <code>false</code> if it is occluded by objects in front of it.
300+ */
272301 /**jsdoc
273−* 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},
274−* but with an additional distance field.
275−*
276−* @typedef {object} Pointers.DefaultParabolaPointerRenderState
277−* @augments Pointers.ParabolaPointerRenderState
278−* @property {number} distance The distance along the parabola at which to render the end of this Parabola Pointer, if one is defined.
279−*/
302+ * Properties that define the visual appearance of a parabola pointer when the pointer is not intersecting something. These are
303+ * properties of {@link Pointers.ParabolaPointerRenderState} but with an additional property.
304+ * @typedef {object} Pointers.DefaultParabolaPointerRenderState
305+ * @property {number} distance - The distance along the parabola at which to render the end of the parabola pointer.
306+ * @see {@link Pointers.ParabolaPointerRenderState} for the remainder of the properties.
307+ */
280308 /**jsdoc
281−* A set of properties used to define the visual aspect of a Parabola Pointer in the case that the Pointer is intersecting something.
282−*
283−* @typedef {object} Pointers.ParabolaPointerRenderState
284−* @property {string} name When using {@link Pointers.createPointer}, the name of this render state, used by {@link Pointers.setRenderState} and {@link Pointers.editRenderState}
285−* @property {Overlays.OverlayProperties|QUuid} [start] When using {@link Pointers.createPointer}, an optionally defined object to represent the beginning of the Parabola Pointer,
286−* using the properties you would normally pass to {@link Overlays.addOverlay}, plus the type (as a <code>type</code> field).
287−* When returned from {@link Pointers.getPointerProperties}, the ID of the created object if it exists, or a null ID otherwise.
288−* @property {Pointers.ParabolaProperties} [path] When using {@link Pointers.createPointer}, the optionally defined rendering properties of the parabolic path defined by the Parabola Pointer.
289−* Not defined in {@link Pointers.getPointerProperties}.
290−* @property {Overlays.OverlayProperties|QUuid} [end] When using {@link Pointers.createPointer}, an optionally defined object to represent the end of the Parabola Pointer,
291−* using the properties you would normally pass to {@link Overlays.addOverlay}, plus the type (as a <code>type</code> field).
292−* When returned from {@link Pointers.getPointerProperties}, the ID of the created object if it exists, or a null ID otherwise.
293−*/
309+ * Properties that define the visual appearance of a parabola pointer when the pointer is intersecting something.
310+ * @typedef {object} Pointers.ParabolaPointerRenderState
311+ * @property {string} name - When creating using {@link Pointers.createPointer}, the name of the render state.
312+ * @property {Overlays.OverlayProperties|Uuid} [start]
313+ * <p>When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of
314+ * an overlay to render at the start of the parabola pointer. The <code>type</code> property must be specified.</p>
315+ * <p>When getting using {@link Pointers.getPointerProperties}, the ID of the overlay rendered at the start of the
316+ * parabola; <code>null</code> if there is no overlay.
317+ * @property {Pointers.ParabolaPointerPath|Uuid} [path]
318+ * <p>When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of
319+ * the rendered path of the parabola pointer.</p>
320+ * <p>This property is not provided when getting using {@link Pointers.getPointerProperties}.
321+ * @property {Overlays.OverlayProperties|Uuid} [end]
322+ * <p>When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of
323+ * an overlay to render at the end of the ray pointer. The <code>type</code> property must be specified.</p>
324+ * <p>When getting using {@link Pointers.getPointerProperties}, the ID of the overlay rendered at the end of the parabola;
325+ * <code>null</code> if there is no overlay.
326+ */
294327 /**jsdoc
295−* 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.
296−* @typedef {object} Pointers.ParabolaPointerProperties
297−* @property {boolean} [faceAvatar=false] If true, the end of the Pointer will always rotate to face the avatar.
298−* @property {boolean} [centerEndY=true] If false, the end of the Pointer will be moved up by half of its height.
299−* @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.
300−* @property {boolean} [distanceScaleEnd=false] If true, the dimensions of the end of the Pointer will scale linearly with distance.
301−* @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.
302−* @property {boolean} [followNormal=false] If true, the end of the Pointer will rotate to follow the normal of the intersected surface.
303−* @property {number} [followNormalStrength=0.0] The strength of the interpolation between the real normal and the visual normal if followNormal is true. <code>0-1</code>. If 0 or 1,
304−* the normal will follow exactly.
305−* @property {boolean} [enabled=false]
306−* @property {Pointers.ParabolaPointerRenderState[]|Object.<string, Pointers.ParabolaPointerRenderState>} [renderStates] A collection of different visual states to switch between.
307−* When using {@link Pointers.createPointer}, a list of ParabolaPointerRenderStates.
308−* When returned from {@link Pointers.getPointerProperties}, a map between render state names and ParabolaPointerRenderStates.
309−* @property {Pointers.DefaultParabolaPointerRenderState[]|Object.<string, Pointers.DefaultParabolaPointerRenderState>} [defaultRenderStates] A collection of different visual states to use if there is no intersection.
310−* When using {@link Pointers.createPointer}, a list of DefaultParabolaPointerRenderStates.
311−* When returned from {@link Pointers.getPointerProperties}, a map between render state names and DefaultParabolaPointerRenderStates.
312−* @property {boolean} [hover=false] If this Pointer should generate hover events.
313−* @property {Pointers.Trigger[]} [triggers] A list of different triggers mechanisms that control this Pointer's click event generation.
314−*/
328+ * The properties of a parabola pointer. These include the properties from the underlying parabola pick that the pointer uses.
329+ * @typedef {object} Pointers.ParabolaPointerProperties
330+ * @property {boolean} [faceAvatar=false] - <code>true</code> if the overlay rendered at the end of the ray rotates about the
331+ * world y-axis to always face the avatar; <code>false</code> if it maintains its world orientation.
332+ * @property {boolean} [centerEndY=true] - <code>true</code> if the overlay rendered at the end of the ray is centered on
333+ * the ray end; <code>false</code> if the overlay is rendered adjacent to the surface if <code>followNormal</code> is
334+ * <code>true</code> or on top of the ray end if if <code>followNormal</code> is <code>false</code>.
335+* @property {boolean} [lockEnd=false] - <code>true</code> if the end of the ray is locked to the center of the object at
336+ * which the ray is pointing; <code>false</code> if the end of the ray is at the intersected surface.
337+ * @property {boolean} [distanceScaleEnd=false] - <code>true</code> if the dimensions of the overlay at the end of the ray
338+ * scale linearly with distance; <code>false</code> if they aren't.
339+ * @property {boolean} [scaleWithParent=false] - <code>true</code> if the width of the ray's path and the size of the
340+ * start and end overlays scale linearly with the pointer parent's scale; <code>false</code> if they don't scale.
341+ * @property {boolean} [scaleWithAvatar=false] - A synonym for <code>scalewithParent</code>.
342+ * <p class="important">Deprecated: This property is deprecated and will be removed.</p>
343+ * @property {boolean} [followNormal=false] - <code>true</code> if the overlay rendered at the end of the ray rotates to
344+ * follow the normal of the surface if one is intersected; <code>false</code> if it doesn't.
345+ * @property {number} [followNormalStrength=0.0] - How quickly the overlay rendered at the end of the ray rotates to follow
346+ * the normal of an intersected surface. If <code>0</code> or <code>1</code>, the overlay rotation follows instantaneously;
347+ * for other values, the larger the value the more quickly the rotation follows.
348+ * @property {Pointers.ParabolaPointerRenderState[]|Object.<string, Pointers.ParabolaPointerRenderState>} [renderStates]
349+ * <p>A set of visual states that can be switched among using {@link Pointers.setRenderState}. These define the visual
350+ * appearance of the pointer when it is intersecting something.</p>
351+ * <p>When setting using {@link Pointers.createPointer}, an array of
352+ * {@link Pointers.ParabolaPointerRenderState|ParabolaPointerRenderState} values.</p>
353+ * <p>When getting using {@link Pointers.getPointerProperties}, an object mapping render state names to
354+ * {@link Pointers.ParabolaPointerRenderState|ParabolaPointerRenderState} values.</p>
355+ * @property {Pointers.DefaultParabolaPointerRenderState[]|Object.<string, Pointers.DefaultParabolaPointerRenderState>}
356+ * [defaultRenderStates]
357+ * <p>A set of visual states that can be switched among using {@link Pointers.setRenderState}. These define the visual
358+ * appearance of the pointer when it is not intersecting something.</p>
359+ * <p>When setting using {@link Pointers.createPointer}, an array of
360+ * {@link Pointers.DefaultParabolaPointerRenderState|DefaultParabolaPointerRenderState} values.</p>
361+ * <p>When getting using {@link Pointers.getPointerProperties}, an object mapping render state names to
362+ * {@link Pointers.DefaultParabolaPointerRenderState|DefaultParabolaPointerRenderState} values.</p>
363+ * @property {boolean} [hover=false] - <code>true</code> if the pointer generates {@link Entities} hover events,
364+ * <code>false</code> if it doesn't.
365+ * @property {Pointers.Trigger[]} [triggers=[]] - A list of ways that a {@link Controller} action or function should trigger
366+ * events on the entity or overlay currently intersected.
367+ * @see {@link Picks.ParabolaPickProperties} for additional properties from the underlying parabola pick.
368+ */
315369 unsigned int PointerScriptingInterface::createParabolaPointer(const QVariant& properties) const {
316370 QVariantMap propertyMap = properties.toMap();
317371