Mirrors/overte
3
0
Fork 0
mirror of https://github.com/overte-org/overte.git synced 2025-04-09 13:02:24 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Merge branch 'master' of github.com:highfidelity/hifi into nut

Browse source
This commit is contained in:
Sam Gateau 2019-07-04 23:24:34 +02:00
commit 98f4448813
6 changed files with 568 additions and 249 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

113
interface/src/raypick/LaserPointerScriptingInterface.h
View file

@ -21,121 +21,146 @@ class LaserPointerScriptingInterface : public QObject, public Dependency {
SINGLETON_DEPENDENCY
/**jsdoc
* Synonym for {@link Pointers} as used for laser pointers. Deprecated.
* The <code>LaserPointers</code> API is a subset of the {@link Pointers} API. It lets you create, manage, and visually
* represent objects for repeatedly calculating ray intersections with avatars, entities, and overlays. Ray pointers can also
* be configured to generate events on entities and overlays intersected.
*
* <p class="important">Deprecated: This API is deprecated. Use {@link Pointers} instead.
*
* @namespace LaserPointers
*
* @hifi-interface
* @hifi-client-entity
* @hifi-avatar
*
* @borrows Pointers.enablePointer as enableLaserPointer
* @borrows Pointers.disablePointer as disableLaserPointer
* @borrows Pointers.removePointer as removeLaserPointer
* @borrows Pointers.setPrecisionPicking as setPrecisionPicking
*/
public:
/**jsdoc
* Creates a new ray pointer. The pointer can have a wide range of behaviors depending on the properties specified. For
* example, it may be a static ray pointer, a mouse ray pointer, or joint ray pointer.
* <p><strong>Warning:</strong> Pointers created using this method currently always intersect at least visible and
* collidable things but this may not always be the case.</p>
* @function LaserPointers.createLaserPointer
* @param {Pointers.LaserPointerProperties} properties
* @returns {number}
* @param {Pointers.RayPointerProperties} properties - The properties of the pointer, including the properties of the
* underlying pick that the pointer uses to do its picking.
* @returns {number} The ID of the pointer if successfully created, otherwise <code>0</code>.
*/
Q_INVOKABLE unsigned int createLaserPointer(const QVariant& properties) const;
/**jsdoc
* @function LaserPointers.enableLaserPointer
* @param {number} id
*/
// jsdoc @borrows from Pointers
Q_INVOKABLE void enableLaserPointer(unsigned int uid) const { DependencyManager::get<PointerManager>()->enablePointer(uid); }
/**jsdoc
* @function LaserPointers.disableLaserPointer
* @param {number} id
*/
// jsdoc @borrows from Pointers
Q_INVOKABLE void disableLaserPointer(unsigned int uid) const { DependencyManager::get<PointerManager>()->disablePointer(uid); }
/**jsdoc
* @function LaserPointers.removeLaserPointer
* @param {number} id
*/
// jsdoc @borrows from Pointers
Q_INVOKABLE void removeLaserPointer(unsigned int uid) const { DependencyManager::get<PointerManager>()->removePointer(uid); }
/**jsdoc
* Edits a render state of a pointer, to change its visual appearance for the state when the pointer is intersecting
* something.
* <p><strong>Note:</strong> You can only edit the properties of the existing parts of the pointer; you cannot change the
* type of any part.</p>
* <p><strong>Note:</strong> You cannot use this method to change the appearance of a default render state.</p>
* @function LaserPointers.editRenderState
* @param {number} id
* @param {string} renderState
* @param {Pointers.RayPointerRenderState} properties
* @param {number} id - The ID of the pointer.
* @param {string} renderState - The name of the render state to edit.
* @param {Pointers.RayPointerRenderState} properties - The new properties for the render state. Only the overlay
* properties to change need be specified.
*/
Q_INVOKABLE void editRenderState(unsigned int uid, const QString& renderState, const QVariant& properties) const;
/**jsdoc
* Sets the render state of a pointer, to change its visual appearance and possibly disable or enable it.
* @function LaserPointers.setRenderState
* @param {string} renderState
* @param {number} id
* @param {string} renderState - <p>The name of the render state to set the pointer to. This may be:</p>
* <ul>
* <li>The name of one of the render states set in the pointer's properties.</li>
* <li><code>""</code>, to hide the pointer and disable emitting of events.</li>
* </ul>
* @param {number} id - The ID of the pointer.
*/
Q_INVOKABLE void setRenderState(unsigned int uid, const QString& renderState) const { DependencyManager::get<PointerManager>()->setRenderState(uid, renderState.toStdString()); }
/**jsdoc
* Gets the most recent intersection of a pointer. A pointer continues to be updated ready to return a result, as long as
* it is enabled, regardless of the render state.
* @function LaserPointers.getPrevRayPickResult
* @param {number} id
* @returns {RayPickResult}
* @param {number} id - The ID of the pointer.
* @returns {RayPickResult} The most recent intersection of the pointer.
*/
Q_INVOKABLE QVariantMap getPrevRayPickResult(unsigned int uid) const;
/**jsdoc
* @function LaserPointers.setPrecisionPicking
* @param {number} id
* @param {boolean} precisionPicking
*/
// jsdoc @borrows from Pointers
Q_INVOKABLE void setPrecisionPicking(unsigned int uid, bool precisionPicking) const { DependencyManager::get<PointerManager>()->setPrecisionPicking(uid, precisionPicking); }
/**jsdoc
* Sets the length of a pointer.
* @function LaserPointers.setLaserLength
* @param {number} id
* @param {number} laserLength
* @param {number} id - The ID of the pointer.
* @param {number} laserLength - The desired length of the pointer.
*/
Q_INVOKABLE void setLaserLength(unsigned int uid, float laserLength) const { DependencyManager::get<PointerManager>()->setLength(uid, laserLength); }
/**jsdoc
* Sets a list of entity and avatar IDs that a pointer should ignore during intersection.
* @function LaserPointers.setIgnoreItems
* @param {number} id
* @param {Uuid[]} ignoreItems
* @param {number} id - The ID of the pointer.
* @param {Uuid[]} ignoreItems - A list of IDs to ignore.
*/
Q_INVOKABLE void setIgnoreItems(unsigned int uid, const QScriptValue& ignoreEntities) const;
/**jsdoc
* Sets a list of entity and avatar IDs that a pointer should include during intersection, instead of intersecting with
* everything.
* @function LaserPointers.setIncludeItems
* @param {number} id
* @param {Uuid[]} includeItems
* @param {number} id - The ID of the pointer.
* @param {Uuid[]} includeItems - A list of IDs to include.
*/
Q_INVOKABLE void setIncludeItems(unsigned int uid, const QScriptValue& includeEntities) const;
/**jsdoc
* Locks a pointer onto a specific entity or avatar.
* @function LaserPointers.setLockEndUUID
* @param {number} id
* @param {Uuid} itemID
* @param {boolean} isAvatar
* @param {Mat4} [offsetMat]
* @param {number} id - The ID of the pointer.
* @param {Uuid} targetID - The ID of the entity or avatar to lock the pointer on to.
* @param {boolean} isAvatar - <code>true</code> if the target is an avatar, <code>false</code> if it is an entity.
* @param {Mat4} [offset] - The offset of the target point from the center of the target item. If not specified, the
* pointer locks on to the center of the target item.
*/
Q_INVOKABLE void setLockEndUUID(unsigned int uid, const QUuid& objectID, bool isAvatar, const glm::mat4& offsetMat = glm::mat4()) const { DependencyManager::get<PointerManager>()->setLockEndUUID(uid, objectID, isAvatar, offsetMat); }
/**jsdoc
* Checks if a pointer is associated with the left hand: a pointer with <code>joint</code> property set to
* <code>"_CONTROLLER_LEFTHAND"</code> or <code>"_CAMERA_RELATIVE_CONTROLLER_LEFTHAND"</code>.
* @function LaserPointers.isLeftHand
* @param {number} id
* @returns {boolean}
* @param {number} id - The ID of the pointer.
* @returns {boolean} <code>true</code> if the pointer is associated with the left hand, <code>false</code> if it isn't.
*/
Q_INVOKABLE bool isLeftHand(unsigned int uid) { return DependencyManager::get<PointerManager>()->isLeftHand(uid); }
/**jsdoc
* Checks if a pointer is associated with the right hand: a pointer with <code>joint</code> property set to
* <code>"_CONTROLLER_RIGHTHAND"</code> or <code>"_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND"</code>.
* @function LaserPointers.isRightHand
* @param {number} id
* @returns {boolean}
* @param {number} id - The ID of the pointer.
* @returns {boolean} <code>true</code> if the pointer is associated with the right hand, <code>false</code> if it isn't.
*/
Q_INVOKABLE bool isRightHand(unsigned int uid) { return DependencyManager::get<PointerManager>()->isRightHand(uid); }
/**jsdoc
* Checks if a pointer is associated with the system mouse: a pointer with <code>joint</code> property set to
* <code>"Mouse"</code>.
* @function LaserPointers.isMouse
* @param {number} id
* @returns {boolean}
* @param {number} id - The ID of the pointer.
* @returns {boolean} <code>true</code> if the pointer is associated with the system mouse, <code>false</code> if it isn't.
*/
Q_INVOKABLE bool isMouse(unsigned int uid) { return DependencyManager::get<PointerManager>()->isMouse(uid); }
};

8
interface/src/raypick/PickScriptingInterface.cpp
View file

@ -55,7 +55,7 @@ PickFilter getPickFilter(unsigned int filter) {
}
/**jsdoc
* A set of properties that can be passed to {@link Picks.createPick} when creating a new ray pick.
* The properties of a ray pick.
*
* @typedef {object} Picks.RayPickProperties
* @property {boolean} [enabled=false] - <code>true</code> if this pick should start enabled, <code>false</code> if it should
@ -138,7 +138,7 @@ unsigned int PickScriptingInterface::createRayPick(const QVariant& properties) {
}
/**jsdoc
* A set of properties that can be passed to {@link Picks.createPick} when creating a new stylus pick.
* The properties of a stylus pick.
*
* @typedef {object} Picks.StylusPickProperties
* @property {number} [hand=-1] <code>0</code> for the left hand, <code>1</code> for the right hand, invalid (<code>-1</code>)
@ -189,7 +189,7 @@ unsigned int PickScriptingInterface::createStylusPick(const QVariant& properties
// NOTE: Laser pointer still uses scaleWithAvatar. Until scaleWithAvatar is also deprecated for pointers, scaleWithAvatar should not be removed from the pick API.
/**jsdoc
* A set of properties that can be passed to {@link Picks.createPick} when creating a new parabola pick.
* The properties of a parabola pick.
*
* @typedef {object} Picks.ParabolaPickProperties
* @property {boolean} [enabled=false] - <code>true</code> if this pick should start enabled, <code>false</code> if it should
@ -297,7 +297,7 @@ unsigned int PickScriptingInterface::createParabolaPick(const QVariant& properti
/**jsdoc
* A set of properties that can be passed to {@link Picks.createPick} when creating a new collision pick.
* The properties of a collision pick.
*
* @typedef {object} Picks.CollisionPickProperties
* @property {boolean} [enabled=false] - <code>true</code> if this pick should start enabled, <code>false</code> if it should

25
interface/src/raypick/PickScriptingInterface.h
View file

@ -194,7 +194,8 @@ public:
Q_INVOKABLE QVariantMap getPrevPickResult(unsigned int uid);
/**jsdoc
* Sets whether or not to use precision picking, i.e., whether to pick against precise meshes or coarse meshes.
* Sets whether or not a pick should use precision picking, i.e., whether it should pick against precise meshes or coarse
* meshes.
* This has the same effect as using the <code>PICK_PRECISE</code> or <code>PICK_COARSE</code> filter flags.
* @function Picks.setPrecisionPicking
* @param {number} id - The ID of the pick.
@ -203,7 +204,7 @@ public:
Q_INVOKABLE void setPrecisionPicking(unsigned int uid, bool precisionPicking);
/**jsdoc
* Sets a list of entity and avatar IDs to ignore during intersection.
* Sets a list of entity and avatar IDs that a pick should ignore during intersection.
* <p><strong>Note:</strong> Not used by stylus picks.</p>
* @function Picks.setIgnoreItems
* @param {number} id - The ID of the pick.
@ -212,8 +213,9 @@ public:
Q_INVOKABLE void setIgnoreItems(unsigned int uid, const QScriptValue& ignoreItems);
/**jsdoc
* Sets a list of entity IDs and/or avatar IDs to include during intersection, instead of intersecting with everything.
* <p><strong>Note:</strong> Stylus picks only intersect with objects in their include list.</p>
* Sets a list of entity and avatar IDs that a pick should include during intersection, instead of intersecting with
* everything.
* <p><strong>Note:</strong> Stylus picks only intersect with items in their include list.</p>
* @function Picks.setIncludeItems
* @param {number} id - The ID of the pick.
* @param {Uuid[]} includeItems - The list of IDs to include.
@ -221,9 +223,9 @@ public:
Q_INVOKABLE void setIncludeItems(unsigned int uid, const QScriptValue& includeItems);
/**jsdoc
* Checks if a pick is associated with the left hand: a ray or parabola pick with joint set to
* <code>"_CONTROLLER_LEFTHAND"</code> or <code>"_CAMERA_RELATIVE_CONTROLLER_LEFTHAND"</code>, or a stylus pick with hand
* set to <code>0</code>.
* Checks if a pick is associated with the left hand: a ray or parabola pick with <code>joint</code> property set to
* <code>"_CONTROLLER_LEFTHAND"</code> or <code>"_CAMERA_RELATIVE_CONTROLLER_LEFTHAND"</code>, or a stylus pick with
* <code>hand</code> property set to <code>0</code>.
* @function Picks.isLeftHand
* @param {number} id - The ID of the pick.
* @returns {boolean} <code>true</code> if the pick is associated with the left hand, <code>false</code> if it isn't.
@ -231,9 +233,9 @@ public:
Q_INVOKABLE bool isLeftHand(unsigned int uid);
/**jsdoc
* Checks if a pick is associated with the right hand: a ray or parabola pick with joint set to
* <code>"_CONTROLLER_RIGHTHAND"</code> or <code>"_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND"</code>, or a stylus pick with hand
* set to <code>1</code>.
* Checks if a pick is associated with the right hand: a ray or parabola pick with <code>joint</code> property set to
* <code>"_CONTROLLER_RIGHTHAND"</code> or <code>"_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND"</code>, or a stylus pick with
* <code>hand</code> property set to <code>1</code>.
* @function Picks.isRightHand
* @param {number} id - The ID of the pick.
* @returns {boolean} <code>true</code> if the pick is associated with the right hand, <code>false</code> if it isn't.
@ -241,7 +243,8 @@ public:
Q_INVOKABLE bool isRightHand(unsigned int uid);
/**jsdoc
* Checks if a pick is associated with the system mouse: a ray or parabola pick with joint set to <code>"Mouse"</code>.
* Checks if a pick is associated with the system mouse: a ray or parabola pick with <code>joint</code> property set to
* <code>"Mouse"</code>.
* @function Picks.isMouse
* @param {number} id - The ID of the pick.
* @returns {boolean} <code>true</code> if the pick is associated with the system mouse, <code>false</code> if it isn't.

251
interface/src/raypick/PointerScriptingInterface.cpp
View file

@ -51,21 +51,22 @@ unsigned int PointerScriptingInterface::createPointer(const PickQuery::PickType&
}
/**jsdoc
* A set of properties that can be passed to {@link Pointers.createPointer} to create a new Pointer. Contains the relevant {@link Picks.PickProperties} to define the underlying Pick.
* The properties of a stylus pointer. These include the properties from the underlying stylus pick that the pointer uses.
* @typedef {object} Pointers.StylusPointerProperties
* @property {boolean} [hover=false] If this pointer should generate hover events.
* @property {boolean} [enabled=false]
* @property {Vec3} [tipOffset] The specified offset of the from the joint index.
* @property {Pointers.StylusPointerProperties.model} [model] Data to replace the default model url, positionOffset and rotationOffset.
* @property {Pointers.StylusPointerModel} [model] - Override some or all of the default stylus model properties.
* @property {boolean} [hover=false] - <code>true</code> if the pointer generates {@link Entities} hover events,
* <code>false</code> if it doesn't.
* @see {@link Picks.StylusPickProperties} for additional properties from the underlying stylus pick.
*/
/**jsdoc
* The properties of a stylus pointer model.
* @typedef {object} Pointers.StylusPointerModel
* @property {string} [url] - The url of a model to use for the stylus, to override the default stylus mode.
* @property {Vec3} [dimensions] - The dimensions of the stylus, to override the default stylus dimensions.
* @property {Vec3} [positionOffset] - The position offset of the model from the stylus tip, to override the default position
* offset.
* @property {Quat} [rotationOffset] - The rotation offset of the model from the hand, to override the default rotation offset.
*/
/**jsdoc
* properties defining stylus pick model that can be included to {@link Pointers.StylusPointerProperties}
* @typedef {object} Pointers.StylusPointerProperties.model
* @property {string} [url] url to the model
* @property {Vec3} [dimensions] the dimensions of the model
* @property {Vec3} [positionOffset] the position offset of the model from the stylus tip.
* @property {Vec3} [rotationOffset] the rotation offset of the model from the parent joint index
*/
unsigned int PointerScriptingInterface::createStylus(const QVariant& properties) const {
QVariantMap propertyMap = properties.toMap();
@ -104,48 +105,76 @@ unsigned int PointerScriptingInterface::createStylus(const QVariant& properties)
}
/**jsdoc
* A set of properties used to define the visual aspect of a Ray Pointer in the case that the Pointer is not intersecting something. Same as a {@link Pointers.RayPointerRenderState},
* but with an additional distance field.
*
* Properties that define the visual appearance of a ray pointer when the pointer is not intersecting something. These are the
* properties of {@link Pointers.RayPointerRenderState} but with an additional property.
* @typedef {object} Pointers.DefaultRayPointerRenderState
* @augments Pointers.RayPointerRenderState
* @property {number} distance The distance at which to render the end of this Ray Pointer, if one is defined.
* @property {number} distance - The distance at which to render the end of the ray pointer.
* @see {@link Pointers.RayPointerRenderState} for the remainder of the properties.
*/
/**jsdoc
* A set of properties which define the visual aspect of a Ray Pointer in the case that the Pointer is intersecting something.
*
* Properties that define the visual appearance of a ray pointer when the pointer is intersecting something.
* @typedef {object} Pointers.RayPointerRenderState
* @property {string} name When using {@link Pointers.createPointer}, the name of this render state, used by {@link Pointers.setRenderState} and {@link Pointers.editRenderState}
* @property {Overlays.OverlayProperties|QUuid} [start] When using {@link Pointers.createPointer}, an optionally defined object to represent the beginning of the Ray Pointer,
* using the properties you would normally pass to {@link Overlays.addOverlay}, plus the type (as a <code>type</code> field).
* When returned from {@link Pointers.getPointerProperties}, the ID of the created object if it exists, or a null ID otherwise.
* @property {Overlays.OverlayProperties|QUuid} [path] When using {@link Pointers.createPointer}, an optionally defined object to represent the path of the Ray Pointer,
* using the properties you would normally pass to {@link Overlays.addOverlay}, plus the type (as a <code>type</code> field), which <b>must</b> be <code>"line3d"</code>.
* When returned from {@link Pointers.getPointerProperties}, the ID of the created object if it exists, or a null ID otherwise.
* @property {Overlays.OverlayProperties|QUuid} [end] When using {@link Pointers.createPointer}, an optionally defined object to represent the end of the Ray Pointer,
* using the properties you would normally pass to {@link Overlays.addOverlay}, plus the type (as a <code>type</code> field).
* When returned from {@link Pointers.getPointerProperties}, the ID of the created object if it exists, or a null ID otherwise.
* @property {string} name - When creating using {@link Pointers.createPointer}, the name of the render state.
* @property {Overlays.OverlayProperties|Uuid} [start]
* <p>When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of
* an overlay to render at the start of the ray pointer. The <code>type</code> property must be specified.</p>
* <p>When getting using {@link Pointers.getPointerProperties}, the ID of the overlay rendered at the start of the ray;
* <code>null</code> if there is no overlay.
*
* @property {Overlays.OverlayProperties|Uuid} [path]
* <p>When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of
* the overlay rendered for the path of the ray pointer. The <code>type</code> property must be specified and be
* <code>"line3d"</code>.</p>
* <p>When getting using {@link Pointers.getPointerProperties}, the ID of the overlay rendered for the path of the ray;
* <code>null</code> if there is no overlay.
*
* @property {Overlays.OverlayProperties|Uuid} [end]
* <p>When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of
* an overlay to render at the end of the ray pointer. The <code>type</code> property must be specified.</p>
* <p>When getting using {@link Pointers.getPointerProperties}, the ID of the overlay rendered at the end of the ray;
* <code>null</code> if there is no overlay.
*/
/**jsdoc
* A set of properties that can be passed to {@link Pointers.createPointer} to create a new Pointer. Contains the relevant {@link Picks.PickProperties} to define the underlying Pick.
* @typedef {object} Pointers.LaserPointerProperties
* @property {boolean} [faceAvatar=false] If true, the end of the Pointer will always rotate to face the avatar.
* @property {boolean} [centerEndY=true] If false, the end of the Pointer will be moved up by half of its height.
* @property {boolean} [lockEnd=false] If true, the end of the Pointer will lock on to the center of the object at which the pointer is pointing.
* @property {boolean} [distanceScaleEnd=false] If true, the dimensions of the end of the Pointer will scale linearly with distance.
* @property {boolean} [scaleWithParent=false] If true, the width of the Pointer's path will scale linearly with the pick parent's scale. scaleWithAvatar is an alias but is deprecated.
* @property {boolean} [followNormal=false] If true, the end of the Pointer will rotate to follow the normal of the intersected surface.
* @property {number} [followNormalStrength=0.0] The strength of the interpolation between the real normal and the visual normal if followNormal is true. <code>0-1</code>. If 0 or 1,
* the normal will follow exactly.
* @property {boolean} [enabled=false]
* @property {Pointers.RayPointerRenderState[]|Object.<string, Pointers.RayPointerRenderState>} [renderStates] A collection of different visual states to switch between.
* When using {@link Pointers.createPointer}, a list of RayPointerRenderStates.
* When returned from {@link Pointers.getPointerProperties}, a map between render state names and RayPointRenderStates.
* @property {Pointers.DefaultRayPointerRenderState[]|Object.<string, Pointers.DefaultRayPointerRenderState>} [defaultRenderStates] A collection of different visual states to use if there is no intersection.
* When using {@link Pointers.createPointer}, a list of DefaultRayPointerRenderStates.
* When returned from {@link Pointers.getPointerProperties}, a map between render state names and DefaultRayPointRenderStates.
* @property {boolean} [hover=false] If this Pointer should generate hover events.
* @property {Pointers.Trigger[]} [triggers] A list of different triggers mechanisms that control this Pointer's click event generation.
* The properties of a ray pointer. These include the properties from the underlying ray pick that the pointer uses.
* @typedef {object} Pointers.RayPointerProperties
* @property {boolean} [faceAvatar=false] - <code>true</code> if the overlay rendered at the end of the ray rotates about the
* world y-axis to always face the avatar; <code>false</code> if it maintains its world orientation.
* @property {boolean} [centerEndY=true] - <code>true</code> if the overlay rendered at the end of the ray is centered on
* the ray end; <code>false</code> if the overlay is positioned against the surface if <code>followNormal</code> is
* <code>true</code>, or above the ray end if <code>followNormal</code> is <code>false</code>.
* @property {boolean} [lockEnd=false] - <code>true</code> if the end of the ray is locked to the center of the object at
* which the ray is pointing; <code>false</code> if the end of the ray is at the intersected surface.
* @property {boolean} [distanceScaleEnd=false] - <code>true</code> if the dimensions of the overlay at the end of the ray
* scale linearly with distance; <code>false</code> if they aren't.
* @property {boolean} [scaleWithParent=false] - <code>true</code> if the width of the ray's path and the size of the
* start and end overlays scale linearly with the pointer parent's scale; <code>false</code> if they don't scale.
* @property {boolean} [scaleWithAvatar=false] - A synonym for <code>scalewithParent</code>.
* <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @property {boolean} [followNormal=false] - <code>true</code> if the overlay rendered at the end of the ray rotates to
* follow the normal of the surface if one is intersected; <code>false</code> if it doesn't.
* @property {number} [followNormalStrength=0.0] - How quickly the overlay rendered at the end of the ray rotates to follow
* the normal of an intersected surface. If <code>0</code> or <code>1</code>, the overlay rotation follows instantaneously;
* for other values, the larger the value the more quickly the rotation follows.
* @property {Pointers.RayPointerRenderState[]|Object.<string, Pointers.RayPointerRenderState>} [renderStates]
* <p>A set of visual states that can be switched among using {@link Pointers.setRenderState}. These define the visual
* appearance of the pointer when it is intersecting something.</p>
* <p>When setting using {@link Pointers.createPointer}, an array of
* {@link Pointers.RayPointerRenderState|RayPointerRenderState} values.</p>
* <p>When getting using {@link Pointers.getPointerProperties}, an object mapping render state names to
* {@link Pointers.RayPointerRenderState|RayPointerRenderState} values.</p>
* @property {Pointers.DefaultRayPointerRenderState[]|Object.<string, Pointers.DefaultRayPointerRenderState>}
* [defaultRenderStates]
* <p>A set of visual states that can be switched among using {@link Pointers.setRenderState}. These define the visual
* appearance of the pointer when it is not intersecting something.</p>
* <p>When setting using {@link Pointers.createPointer}, an array of
* {@link Pointers.DefaultRayPointerRenderState|DefaultRayPointerRenderState} values.</p>
* <p>When getting using {@link Pointers.getPointerProperties}, an object mapping render state names to
* {@link Pointers.DefaultRayPointerRenderState|DefaultRayPointerRenderState} values.</p>
* @property {boolean} [hover=false] - <code>true</code> if the pointer generates {@link Entities} hover events,
* <code>false</code> if it doesn't.
* @property {Pointers.Trigger[]} [triggers=[]] - A list of ways that a {@link Controller} action or function should trigger
* events on the entity or overlay currently intersected.
* @see {@link Picks.RayPickProperties} for additional properties from the underlying ray pick.
*/
unsigned int PointerScriptingInterface::createLaserPointer(const QVariant& properties) const {
QVariantMap propertyMap = properties.toMap();
@ -260,58 +289,84 @@ unsigned int PointerScriptingInterface::createLaserPointer(const QVariant& prope
}
/**jsdoc
* The rendering properties of the parabolic path
*
* @typedef {object} Pointers.ParabolaProperties
* @property {Color} color=255,255,255 The color of the parabola.
* @property {number} alpha=1.0 The alpha of the parabola.
* @property {number} width=0.01 The width of the parabola, in meters.
* @property {boolean} isVisibleInSecondaryCamera=false The width of the parabola, in meters.
* @property {boolean} drawInFront=false If <code>true</code>, the parabola is rendered in front of other items in the scene.
*/
* The visual appearance of the parabolic path.
* @typedef {object} Pointers.ParabolaPointerPath
* @property {Color} [color=255,255,255] - The color of the parabola.
* @property {number} [alpha=1.0] - The opacity of the parabola, range <code>0.0</code> &ndash; <code>1.0</code>.
* @property {number} [width=0.01] - The width of the parabola, in meters.
* @property {boolean} [isVisibleInSecondaryCamera=false] - <code>true</code> if the parabola is rendered in the secondary
* camera, <code>false</code> if it isn't.
* @property {boolean} [drawInFront=false] - <code>true</code> if the parabola is rendered in front of objects in the world,
* but behind the HUD, <code>false</code> if it is occluded by objects in front of it.
*/
/**jsdoc
* A set of properties used to define the visual aspect of a Parabola Pointer in the case that the Pointer is not intersecting something. Same as a {@link Pointers.ParabolaPointerRenderState},
* but with an additional distance field.
*
* @typedef {object} Pointers.DefaultParabolaPointerRenderState
* @augments Pointers.ParabolaPointerRenderState
* @property {number} distance The distance along the parabola at which to render the end of this Parabola Pointer, if one is defined.
*/
* Properties that define the visual appearance of a parabola pointer when the pointer is not intersecting something. These are
* properties of {@link Pointers.ParabolaPointerRenderState} but with an additional property.
* @typedef {object} Pointers.DefaultParabolaPointerRenderState
* @property {number} distance - The distance along the parabola at which to render the end of the parabola pointer.
* @see {@link Pointers.ParabolaPointerRenderState} for the remainder of the properties.
*/
/**jsdoc
* A set of properties used to define the visual aspect of a Parabola Pointer in the case that the Pointer is intersecting something.
*
* @typedef {object} Pointers.ParabolaPointerRenderState
* @property {string} name When using {@link Pointers.createPointer}, the name of this render state, used by {@link Pointers.setRenderState} and {@link Pointers.editRenderState}
* @property {Overlays.OverlayProperties|QUuid} [start] When using {@link Pointers.createPointer}, an optionally defined object to represent the beginning of the Parabola Pointer,
* using the properties you would normally pass to {@link Overlays.addOverlay}, plus the type (as a <code>type</code> field).
* When returned from {@link Pointers.getPointerProperties}, the ID of the created object if it exists, or a null ID otherwise.
* @property {Pointers.ParabolaProperties} [path] When using {@link Pointers.createPointer}, the optionally defined rendering properties of the parabolic path defined by the Parabola Pointer.
* Not defined in {@link Pointers.getPointerProperties}.
* @property {Overlays.OverlayProperties|QUuid} [end] When using {@link Pointers.createPointer}, an optionally defined object to represent the end of the Parabola Pointer,
* using the properties you would normally pass to {@link Overlays.addOverlay}, plus the type (as a <code>type</code> field).
* When returned from {@link Pointers.getPointerProperties}, the ID of the created object if it exists, or a null ID otherwise.
*/
* Properties that define the visual appearance of a parabola pointer when the pointer is intersecting something.
* @typedef {object} Pointers.ParabolaPointerRenderState
* @property {string} name - When creating using {@link Pointers.createPointer}, the name of the render state.
* @property {Overlays.OverlayProperties|Uuid} [start]
* <p>When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of
* an overlay to render at the start of the parabola pointer. The <code>type</code> property must be specified.</p>
* <p>When getting using {@link Pointers.getPointerProperties}, the ID of the overlay rendered at the start of the
* parabola; <code>null</code> if there is no overlay.
* @property {Pointers.ParabolaPointerPath|Uuid} [path]
* <p>When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of
* the rendered path of the parabola pointer.</p>
* <p>This property is not provided when getting using {@link Pointers.getPointerProperties}.
* @property {Overlays.OverlayProperties|Uuid} [end]
* <p>When creating or editing using {@link Pointers.createPointer} or {@link Pointers.editRenderState}, the properties of
* an overlay to render at the end of the ray pointer. The <code>type</code> property must be specified.</p>
* <p>When getting using {@link Pointers.getPointerProperties}, the ID of the overlay rendered at the end of the parabola;
* <code>null</code> if there is no overlay.
*/
/**jsdoc
* A set of properties that can be passed to {@link Pointers.createPointer} to create a new Pointer. Contains the relevant {@link Picks.PickProperties} to define the underlying Pick.
* @typedef {object} Pointers.ParabolaPointerProperties
* @property {boolean} [faceAvatar=false] If true, the end of the Pointer will always rotate to face the avatar.
* @property {boolean} [centerEndY=true] If false, the end of the Pointer will be moved up by half of its height.
* @property {boolean} [lockEnd=false] If true, the end of the Pointer will lock on to the center of the object at which the pointer is pointing.
* @property {boolean} [distanceScaleEnd=false] If true, the dimensions of the end of the Pointer will scale linearly with distance.
* @property {boolean} [scaleWithParent=true] If true, the width of the Pointer's path will scale linearly with the pick parent's scale. scaleWithAvatar is an alias but is deprecated.
* @property {boolean} [followNormal=false] If true, the end of the Pointer will rotate to follow the normal of the intersected surface.
* @property {number} [followNormalStrength=0.0] The strength of the interpolation between the real normal and the visual normal if followNormal is true. <code>0-1</code>. If 0 or 1,
* the normal will follow exactly.
* @property {boolean} [enabled=false]
* @property {Pointers.ParabolaPointerRenderState[]|Object.<string, Pointers.ParabolaPointerRenderState>} [renderStates] A collection of different visual states to switch between.
* When using {@link Pointers.createPointer}, a list of ParabolaPointerRenderStates.
* When returned from {@link Pointers.getPointerProperties}, a map between render state names and ParabolaPointerRenderStates.
* @property {Pointers.DefaultParabolaPointerRenderState[]|Object.<string, Pointers.DefaultParabolaPointerRenderState>} [defaultRenderStates] A collection of different visual states to use if there is no intersection.
* When using {@link Pointers.createPointer}, a list of DefaultParabolaPointerRenderStates.
* When returned from {@link Pointers.getPointerProperties}, a map between render state names and DefaultParabolaPointerRenderStates.
* @property {boolean} [hover=false] If this Pointer should generate hover events.
* @property {Pointers.Trigger[]} [triggers] A list of different triggers mechanisms that control this Pointer's click event generation.
*/
* The properties of a parabola pointer. These include the properties from the underlying parabola pick that the pointer uses.
* @typedef {object} Pointers.ParabolaPointerProperties
* @property {boolean} [faceAvatar=false] - <code>true</code> if the overlay rendered at the end of the ray rotates about the
* world y-axis to always face the avatar; <code>false</code> if it maintains its world orientation.
* @property {boolean} [centerEndY=true] - <code>true</code> if the overlay rendered at the end of the ray is centered on
* the ray end; <code>false</code> if the overlay is positioned against the surface if <code>followNormal</code> is
* <code>true</code>, or above the ray end if <code>followNormal</code> is <code>false</code>.
* @property {boolean} [lockEnd=false] - <code>true</code> if the end of the ray is locked to the center of the object at
* which the ray is pointing; <code>false</code> if the end of the ray is at the intersected surface.
* @property {boolean} [distanceScaleEnd=false] - <code>true</code> if the dimensions of the overlay at the end of the ray
* scale linearly with distance; <code>false</code> if they aren't.
* @property {boolean} [scaleWithParent=false] - <code>true</code> if the width of the ray's path and the size of the
* start and end overlays scale linearly with the pointer parent's scale; <code>false</code> if they don't scale.
* @property {boolean} [scaleWithAvatar=false] - A synonym for <code>scalewithParent</code>.
* <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @property {boolean} [followNormal=false] - <code>true</code> if the overlay rendered at the end of the ray rotates to
* follow the normal of the surface if one is intersected; <code>false</code> if it doesn't.
* @property {number} [followNormalStrength=0.0] - How quickly the overlay rendered at the end of the ray rotates to follow
* the normal of an intersected surface. If <code>0</code> or <code>1</code>, the overlay rotation follows instantaneously;
* for other values, the larger the value the more quickly the rotation follows.
* @property {Pointers.ParabolaPointerRenderState[]|Object.<string, Pointers.ParabolaPointerRenderState>} [renderStates]
* <p>A set of visual states that can be switched among using {@link Pointers.setRenderState}. These define the visual
* appearance of the pointer when it is intersecting something.</p>
* <p>When setting using {@link Pointers.createPointer}, an array of
* {@link Pointers.ParabolaPointerRenderState|ParabolaPointerRenderState} values.</p>
* <p>When getting using {@link Pointers.getPointerProperties}, an object mapping render state names to
* {@link Pointers.ParabolaPointerRenderState|ParabolaPointerRenderState} values.</p>
* @property {Pointers.DefaultParabolaPointerRenderState[]|Object.<string, Pointers.DefaultParabolaPointerRenderState>}
* [defaultRenderStates]
* <p>A set of visual states that can be switched among using {@link Pointers.setRenderState}. These define the visual
* appearance of the pointer when it is not intersecting something.</p>
* <p>When setting using {@link Pointers.createPointer}, an array of
* {@link Pointers.DefaultParabolaPointerRenderState|DefaultParabolaPointerRenderState} values.</p>
* <p>When getting using {@link Pointers.getPointerProperties}, an object mapping render state names to
* {@link Pointers.DefaultParabolaPointerRenderState|DefaultParabolaPointerRenderState} values.</p>
* @property {boolean} [hover=false] - <code>true</code> if the pointer generates {@link Entities} hover events,
* <code>false</code> if it doesn't.
* @property {Pointers.Trigger[]} [triggers=[]] - A list of ways that a {@link Controller} action or function should trigger
* events on the entity or overlay currently intersected.
* @see {@link Picks.ParabolaPickProperties} for additional properties from the underlying parabola pick.
*/
unsigned int PointerScriptingInterface::createParabolaPointer(const QVariant& properties) const {
QVariantMap propertyMap = properties.toMap();

397
interface/src/raypick/PointerScriptingInterface.h
View file

@ -15,8 +15,9 @@
#include <Pick.h>
/**jsdoc
* The Pointers API lets you create and manage objects for repeatedly calculating intersections in different ways, as well as the visual representation of those objects.
* Pointers can also be configured to automatically generate {@link PointerEvent}s on {@link Entities}.
* The <code>Pointers</code> API lets you create, manage, and visually represent objects for repeatedly calculating
* intersections with avatars, entities, and overlays. Pointers can also be configured to generate events on entities and
* overlays intersected.
*
* @namespace Pointers
*
@ -35,184 +36,416 @@ public:
unsigned int createParabolaPointer(const QVariant& properties) const;
/**jsdoc
* A trigger mechanism for Ray and Parabola Pointers.
*
* @typedef {object} Pointers.Trigger
* @property {Controller.Standard|Controller.Actions|function} action This can be a built-in Controller action, like Controller.Standard.LTClick, or a function that evaluates to >= 1.0 when you want to trigger <code>button</code>.
* @property {string} button Which button to trigger. "Primary", "Secondary", "Tertiary", and "Focus" are currently supported. Only "Primary" will trigger clicks on web surfaces. If "Focus" is triggered,
* it will try to set the entity focus to the object at which the Pointer is aimed. Buttons besides the first three will still trigger events, but event.button will be "None".
*/
* Specifies that a {@link Controller} action or function should trigger events on the entity or overlay currently
* intersected by a {@link Pointers.RayPointerProperties|Ray} or {@link Pointers.ParabolaPointerProperties|Parabola}
* pointer.
* @typedef {object} Pointers.Trigger
* @property {Controller.Standard|Controller.Actions|function} action - The controller output or function that triggers the
* events on the entity or overlay. If a function, it must return a number <code>&gt;= 1.0</code> to start the action
* and <code>&lt; 1.0</code> to terminate the action.
* @property {string} button - Which button to trigger.
* <ul>
* <li><code>"Primary"</code>, <code>"Secondary"</code>, and <code>"Tertiary"</code> cause {@link Entities} and
* {@link Overlays} mouse pointer events. Other button names also cause mouse events but the <code>button</code>
* property in the event will be <code>"None"</code>.</li>
* <li><code>"Focus"</code> will try to give focus to the entity or overlay which the pointer is intersecting.</li>
* </ul>
*/
/**jsdoc
* Adds a new Pointer
* Different {@link PickType}s use different properties, and within one PickType, the properties you choose can lead to a wide range of behaviors. For example,
* with PickType.Ray, depending on which optional parameters you pass, you could create a Static Ray Pointer, a Mouse Ray Pointer, or a Joint Ray Pointer.
* Pointers created with this method always intersect at least visible and collidable things
* Creates a new ray, parabola, or stylus pointer. The pointer can have a wide range of behaviors depending on the
* properties specified. For example, a ray pointer may be a static ray pointer, a mouse ray pointer, or joint ray
* pointer.
* <p><strong>Warning:</strong> Pointers created using this method currently always intersect at least visible and
* collidable things but this may not always be the case.</p>
* @function Pointers.createPointer
* @param {PickType} type A PickType that specifies the method of picking to use. Cannot be {@link PickType|PickType.Collision}.
* @param {Pointers.LaserPointerProperties|Pointers.StylusPointerProperties|Pointers.ParabolaPointerProperties} properties A PointerProperties object, containing all the properties for initializing this Pointer <b>and</b> the {@link Picks.PickProperties} for the Pick that
* this Pointer will use to do its picking.
* @returns {number} The ID of the created Pointer. Used for managing the Pointer. 0 if invalid.
* @param {PickType} type - The type of pointer to create. Cannot be {@link PickType|PickType.Collision}.
* @param {Pointers.RayPointerProperties|Pointers.ParabolaPointerProperties|Pointers.StylusPointerProperties} properties -
* The properties of the pointer, per the pointer <code>type</code>, including the properties of the underlying pick
* that the pointer uses to do its picking.
* @returns {number} The ID of the pointer if successfully created, otherwise <code>0</code>.
*
* @example <caption>Create a left hand Ray Pointer that triggers events on left controller trigger click and changes color when it's intersecting something.</caption>
*
* var end = {
* @example <caption>Create a ray pointer on the left hand that changes color when it's intersecting and that triggers
* events.<br />
* Note: Stop controllerScripts.js from running to disable similar behavior from it.</caption>
* var intersectEnd = {
* type: "sphere",
* dimensions: {x:0.5, y:0.5, z:0.5},
* dimensions: { x: 0.2, y: 0.2, z: 0.2 },
* solid: true,
* color: {red:0, green:255, blue:0},
* color: { red: 0, green: 255, blue: 0 },
* ignorePickIntersection: true
* };
* var end2 = {
* var intersectedPath = {
* type: "line3d",
* color: { red: 0, green: 255, blue: 0 },
* };
* var searchEnd = {
* type: "sphere",
* dimensions: {x:0.5, y:0.5, z:0.5},
* dimensions: { x: 0.2, y: 0.2, z: 0.2 },
* solid: true,
* color: {red:255, green:0, blue:0},
* color: { red: 255, green: 0, blue: 0 },
* ignorePickIntersection: true
* };
*
* var renderStates = [ {name: "test", end: end} ];
* var defaultRenderStates = [ {name: "test", distance: 10.0, end: end2} ];
* var pointer = Pointers.createPointer(PickType.Ray, {
* var searchPath = {
* type: "line3d",
* color: { red: 255, green: 0, blue: 0 },
* };
*
* var renderStates = [{ name: "example", path: intersectedPath, end: intersectEnd }];
* var defaultRenderStates = [{ name: "example", distance: 20.0, path: searchPath, end: searchEnd }];
*
* // Create the pointer.
* var rayPointer = Pointers.createPointer(PickType.Ray, {
* joint: "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND",
* filter: Picks.PICK_LOCAL_ENTITIES | Picks.PICK_DOMAIN_ENTITIES | Picks.PICK_INCLUDE_NONCOLLIDABLE,
* renderStates: renderStates,
* defaultRenderStates: defaultRenderStates,
* distanceScaleEnd: true,
* triggers: [ {action: Controller.Standard.LTClick, button: "Focus"}, {action: Controller.Standard.LTClick, button: "Primary"} ],
* hover: true,
* hover: true, // Generate hover events.
* triggers: [
* { action: Controller.Standard.LTClick, button: "Primary" }, // Generate mouse events.
* { action: Controller.Standard.LTClick, button: "Focus" } // Focus on web entities.
* ],
* enabled: true
* });
* Pointers.setRenderState(pointer, "test");
* Pointers.setRenderState(rayPointer, "example");
*
* // Hover events.
* Entities.hoverEnterEntity.connect(function (entityID, event) {
* print("hoverEnterEntity() : " + entityID);
* });
* Entities.hoverLeaveEntity.connect(function (entityID, event) {
* print("hoverLeaveEntity() : " + entityID);
* });
*
* // Mouse events.
* Entities.mousePressOnEntity.connect(function (entityID, event) {
* print("mousePressOnEntity() : " + entityID + " , " + event.button);
* });
* Entities.mouseReleaseOnEntity.connect(function (entityID, event) {
* print("mouseReleaseOnEntity() : " + entityID + " , " + event.button);
* });
*
* // Tidy up.
* Script.scriptEnding.connect(function () {
* Pointers.removePointer(rayPointer);
* });
*/
// TODO: expand Pointers to be able to be fully configurable with PickFilters
Q_INVOKABLE unsigned int createPointer(const PickQuery::PickType& type, const QVariant& properties);
/**jsdoc
* Enables a Pointer.
* Enables and shows a pointer. Enabled pointers update their pick results and generate events.
* @function Pointers.enablePointer
* @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}.
* @param {number} id - The ID of the pointer.
*/
Q_INVOKABLE void enablePointer(unsigned int uid) const { DependencyManager::get<PointerManager>()->enablePointer(uid); }
/**jsdoc
* Disables a Pointer.
* Disables and hides a pointer. Disabled pointers do not update their pick results or generate events.
* @function Pointers.disablePointer
* @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}.
* @param {number} id - The ID of the pointer.
*/
Q_INVOKABLE void disablePointer(unsigned int uid) const { DependencyManager::get<PointerManager>()->disablePointer(uid); }
/**jsdoc
* Removes a Pointer.
* Removes (deletes) a pointer.
* @function Pointers.removePointer
* @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}.
* @param {number} id - The ID of the pointer.
*/
Q_INVOKABLE void removePointer(unsigned int uid) const { DependencyManager::get<PointerManager>()->removePointer(uid); }
/**jsdoc
* Edit some visual aspect of a Pointer. Currently only supported for Ray Pointers.
* Edits a render state of a {@link Pointers.RayPointerProperties|ray} or
* {@link Pointers.ParabolaPointerProperties|parabola} pointer, to change its visual appearance for the state when the
* pointer is intersecting something.
* <p><strong>Note:</strong> You can only edit the properties of the existing parts of the pointer; you cannot change the
* type of any part.</p>
* <p><strong>Note:</strong> You cannot use this method to change the appearance of a default render state.</p>
* <p><strong>Note:</strong> Not able to be used with stylus pointers.</p>
* @function Pointers.editRenderState
* @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}.
* @param {string} renderState The name of the render state you want to edit.
* @param {Pointers.RayPointerRenderState} properties The new properties for <code>renderStates</code> item.
* @param {number} id - The ID of the pointer.
* @param {string} renderState - The name of the render state to edit.
* @param {Pointers.RayPointerRenderState|Pointers.ParabolaPointerRenderState} properties - The new properties for the
* render state. Only the overlay properties to change need be specified.
* @example <caption>Change the dimensions of a ray pointer's intersecting end overlay.</caption>
* var intersectEnd = {
* type: "sphere",
* dimensions: { x: 0.2, y: 0.2, z: 0.2 },
* solid: true,
* color: { red: 0, green: 255, blue: 0 },
* ignorePickIntersection: true
* };
* var intersectedPath = {
* type: "line3d",
* color: { red: 0, green: 255, blue: 0 },
* };
* var searchEnd = {
* type: "sphere",
* dimensions: { x: 0.2, y: 0.2, z: 0.2 },
* solid: true,
* color: { red: 255, green: 0, blue: 0 },
* ignorePickIntersection: true
* };
* var searchPath = {
* type: "line3d",
* color: { red: 255, green: 0, blue: 0 },
* };
*
* var renderStates = [ { name: "example", path: intersectedPath, end: intersectEnd } ];
* var defaultRenderStates = [ { name: "example", distance: 20.0, path: searchPath, end: searchEnd } ];
*
* // Create the pointer.
* var rayPointer = Pointers.createPointer(PickType.Ray, {
* joint: "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND",
* filter: Picks.PICK_LOCAL_ENTITIES | Picks.PICK_DOMAIN_ENTITIES | Picks.PICK_INCLUDE_NONCOLLIDABLE,
* renderStates: renderStates,
* defaultRenderStates: defaultRenderStates,
* enabled: true
* });
* Pointers.setRenderState(rayPointer, "example");
*
* // Edit the intersecting render state.
* Script.setTimeout(function () {
* print("Edit render state");
* Pointers.editRenderState(rayPointer, "example", {
* end: { dimensions: { x: 0.5, y: 0.5, z: 0.5 } }
* });
* }, 10000);
*
* Script.setTimeout(function () {
* print("Edit render state");
* Pointers.editRenderState(rayPointer, "example", {
* end: { dimensions: { x: 0.2, y: 0.2, z: 0.2 } }
* });
* }, 15000);
*
* // Tidy up.
* Script.scriptEnding.connect(function () {
* Pointers.removePointer(rayPointer);
* });
*/
Q_INVOKABLE void editRenderState(unsigned int uid, const QString& renderState, const QVariant& properties) const;
/**jsdoc
* Set the render state of a Pointer. For Ray Pointers, this means switching between their {@link Pointers.RayPointerRenderState}s, or "" to turn off rendering and hover/trigger events.
* For Stylus Pointers, there are three built-in options: "events on" (render and send events, the default), "events off" (render but don't send events), and "disabled" (don't render, don't send events).
* Sets the render state of a pointer, to change its visual appearance and possibly disable or enable it.
* @function Pointers.setRenderState
* @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}.
* @param {string} renderState The name of the render state to which you want to switch.
* @param {number} id - The ID of the pointer.
* @param {string} renderState - <p>The name of the render state to set the pointer to.</p>
* <p>For {@link Pointers.RayPointerProperties|ray} and {@link Pointers.ParabolaPointerProperties|parabola} pointers,
* this may be:</p>
* <ul>
* <li>The name of one of the render states set in the pointer's properties.</li>
* <li><code>""</code>, to hide the pointer and disable emitting of events.</li>
* </ul>
* <p>For {@link Pointers.StylusPointerProperties|stylus} pointers, the values may be:</p>
* <ul>
* <li><code>"events on"</code>, to render and emit events (the default).</li>
* <li><code>"events off"</code>, to render but don't emit events.</li>
* <li><code>"disabled"</code>, to not render and not emit events.</li>
* </ul>
* @example <caption>Switch a ray pointer between having a path and not having a path.</caption>
* var intersectEnd = {
* type: "sphere",
* dimensions: { x: 0.2, y: 0.2, z: 0.2 },
* solid: true,
* color: { red: 0, green: 255, blue: 0 },
* ignorePickIntersection: true
* };
* var intersectedPath = {
* type: "line3d",
* color: { red: 0, green: 255, blue: 0 },
* };
* var searchEnd = {
* type: "sphere",
* dimensions: { x: 0.2, y: 0.2, z: 0.2 },
* solid: true,
* color: { red: 255, green: 0, blue: 0 },
* ignorePickIntersection: true
* };
* var searchPath = {
* type: "line3d",
* color: { red: 255, green: 0, blue: 0 },
* };
*
* var renderStates = [
* { name: "examplePath", path: intersectedPath, end: intersectEnd },
* { name: "exampleNoPath", end: intersectEnd }
* ];
* var defaultRenderStates = [
* { name: "examplePath", distance: 20.0, path: searchPath, end: searchEnd },
* { name: "exampleNoPath", distance: 20.0, end: searchEnd }
* ];
*
* // Create the pointer.
* var rayPointer = Pointers.createPointer(PickType.Ray, {
* joint: "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND",
* filter: Picks.PICK_LOCAL_ENTITIES | Picks.PICK_DOMAIN_ENTITIES | Picks.PICK_INCLUDE_NONCOLLIDABLE,
* renderStates: renderStates,
* defaultRenderStates: defaultRenderStates,
* enabled: true
* });
* Pointers.setRenderState(rayPointer, "examplePath");
*
* // Change states.
* Script.setTimeout(function () {
* print("Without path");
* Pointers.setRenderState(rayPointer, "exampleNoPath");
* }, 10000);
*
* Script.setTimeout(function () {
* print("With path");
* Pointers.setRenderState(rayPointer, "examplePath");
* }, 15000);
*
* // Tidy up.
* Script.scriptEnding.connect(function () {
* Pointers.removePointer(rayPointer);
* });
*/
Q_INVOKABLE void setRenderState(unsigned int uid, const QString& renderState) const { DependencyManager::get<PointerManager>()->setRenderState(uid, renderState.toStdString()); }
/**jsdoc
* Get the most recent pick result from this Pointer. This will be updated as long as the Pointer is enabled, regardless of the render state.
* Gets the most recent intersection of a pointer. A pointer continues to be updated ready to return a result, as long as
* it is enabled, regardless of the render state.
* @function Pointers.getPrevPickResult
* @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}.
* @returns {RayPickResult|StylusPickResult} The most recent intersection result. This will be slightly different for different PickTypes.
* @param {number} id - The ID of the pointer.
* @returns {RayPickResult|ParabolaPickResult|StylusPickResult} The most recent intersection of the pointer.
*/
Q_INVOKABLE QVariantMap getPrevPickResult(unsigned int uid) const;
/**jsdoc
* Sets whether or not to use precision picking.
* Sets whether or not a pointer should use precision picking, i.e., whether it should pick against precise meshes or
* coarse meshes. This has the same effect as using the <code>PICK_PRECISE</code> or <code>PICK_COARSE</code> filter flags.
* @function Pointers.setPrecisionPicking
* @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}.
* @param {boolean} precisionPicking Whether or not to use precision picking
* @param {number} id - The ID of the pointer.
* @param {boolean} precisionPicking - <code>true</code> to use precision picking, <code>false</code> to use coarse picking.
*/
Q_INVOKABLE void setPrecisionPicking(unsigned int uid, bool precisionPicking) const { DependencyManager::get<PointerManager>()->setPrecisionPicking(uid, precisionPicking); }
/**jsdoc
* Sets the length of this Pointer. No effect on Stylus Pointers.
* Sets the length of a pointer.
* <p><strong>Note:</strong> Not used by stylus pointers.</p>
* @function Pointers.setLength
* @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}.
* @param {number} length The desired length of the Pointer.
* @param {number} id - The ID of the pointer.
* @param {number} length - The desired length of the pointer.
*/
Q_INVOKABLE void setLength(unsigned int uid, float length) const { DependencyManager::get<PointerManager>()->setLength(uid, length); }
/**jsdoc
* Sets a list of Entity IDs and/or Avatar IDs to ignore during intersection. Not used by Stylus Pointers.
* Sets a list of entity and avatar IDs that a pointer should ignore during intersection.
* <p><strong>Note:</strong> Not used by stylus pointers.</p>
* @function Pointers.setIgnoreItems
* @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}.
* @param {Uuid[]} ignoreItems A list of IDs to ignore.
* @param {number} id - The ID of the pointer.
* @param {Uuid[]} ignoreItems - A list of IDs to ignore.
*/
Q_INVOKABLE void setIgnoreItems(unsigned int uid, const QScriptValue& ignoreEntities) const;
/**jsdoc
* Sets a list of Entity IDs and/or Avatar IDs to include during intersection, instead of intersecting with everything. Stylus
* Pointers <b>only</b> intersect with objects in their include list.
* Sets a list of entity and avatar IDs that a pointer should include during intersection, instead of intersecting with
* everything.
* <p><strong>Note:</strong> Stylus pointers only intersect with items in their include list.</p>
* @function Pointers.setIncludeItems
* @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}.
* @param {Uuid[]} includeItems A list of IDs to include.
* @param {number} id - The ID of the pointer.
* @param {Uuid[]} includeItems - A list of IDs to include.
*/
Q_INVOKABLE void setIncludeItems(unsigned int uid, const QScriptValue& includeEntities) const;
/**jsdoc
* Lock a Pointer onto a specific object (entity or avatar). Optionally, provide an offset in object-space, otherwise the Pointer will lock on to the center of the object.
* Not used by Stylus Pointers.
* Locks a pointer onto a specific entity or avatar.
* <p><strong>Note:</strong> Not used by stylus pointers.</p>
* @function Pointers.setLockEndUUID
* @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}.
* @param {Uuid} objectID The ID of the object to which to lock on.
* @param {boolean} isAvatar False for entities, true for avatars
* @param {Mat4} [offsetMat] The offset matrix to use if you do not want to lock on to the center of the object.
* @param {number} id - The ID of the pointer.
* @param {Uuid} targetID - The ID of the entity or avatar to lock the pointer on to.
* @param {boolean} isAvatar - <code>true</code> if the target is an avatar, <code>false</code> if it is an entity.
* @param {Mat4} [offset] - The offset of the target point from the center of the target item. If not specified, the
* pointer locks on to the center of the target item.
*/
Q_INVOKABLE void setLockEndUUID(unsigned int uid, const QUuid& objectID, bool isAvatar, const glm::mat4& offsetMat = glm::mat4()) const { DependencyManager::get<PointerManager>()->setLockEndUUID(uid, objectID, isAvatar, offsetMat); }
/**jsdoc
* Check if a Pointer is associated with the left hand.
* Checks if a pointer is associated with the left hand: a ray or parabola pointer with <code>joint</code> property set to
* <code>"_CONTROLLER_LEFTHAND"</code> or <code>"_CAMERA_RELATIVE_CONTROLLER_LEFTHAND"</code>, or a stylus pointer with
* <code>hand</code> property set to <code>0</code>.
* @function Pointers.isLeftHand
* @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}.
* @returns {boolean} True if the Pointer is a Joint Ray Pointer with joint == "_CONTROLLER_LEFTHAND" or "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND", or a Stylus Pointer with hand == 0
* @param {number} id - The ID of the pointer.
* @returns {boolean} <code>true</code> if the pointer is associated with the left hand, <code>false</code> if it isn't.
*/
Q_INVOKABLE bool isLeftHand(unsigned int uid) { return DependencyManager::get<PointerManager>()->isLeftHand(uid); }
/**jsdoc
* Check if a Pointer is associated with the right hand.
* Checks if a pointer is associated with the right hand: a ray or parabola pointer with <code>joint</code> property set to
* <code>"_CONTROLLER_RIGHTHAND"</code> or <code>"_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND"</code>, or a stylus pointer with
* <code>hand</code> property set to <code>1</code>.
* @function Pointers.isRightHand
* @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}.
* @returns {boolean} True if the Pointer is a Joint Ray Pointer with joint == "_CONTROLLER_RIGHTHAND" or "_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND", or a Stylus Pointer with hand == 1
* @param {number} id - The ID of the pointer.
* @returns {boolean} <code>true</code> if the pointer is associated with the right hand, <code>false</code> if it isn't.
*/
Q_INVOKABLE bool isRightHand(unsigned int uid) { return DependencyManager::get<PointerManager>()->isRightHand(uid); }
/**jsdoc
* Check if a Pointer is associated with the system mouse.
* Checks if a pointer is associated with the system mouse: a ray or parabola pointer with <code>joint</code> property set
* to <code>"Mouse"</code>.
* @function Pointers.isMouse
* @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}.
* @returns {boolean} True if the Pointer is a Mouse Ray Pointer, false otherwise.
* @param {number} id - The ID of the pointer.
* @returns {boolean} <code>true</code> if the pointer is associated with the system mouse, <code>false</code> if it isn't.
*/
Q_INVOKABLE bool isMouse(unsigned int uid) { return DependencyManager::get<PointerManager>()->isMouse(uid); }
/**jsdoc
* Returns information about an existing Pointer
* Gets information about a pointer.
* @function Pointers.getPointerProperties
* @param {number} uid The ID of the Pointer, as returned by {@link Pointers.createPointer}.
* @returns {Pointers.LaserPointerProperties|Pointers.StylusPointerProperties|Pointers.ParabolaPointerProperties} The information about the Pointer.
* Currently only includes renderStates and defaultRenderStates with associated entity IDs.
* @param {number} id - The ID of the pointer.
* @returns {Pointers.RayPointerProperties|Pointers.ParabolaPointerProperties|object} The <code>renderStates</code> and
* <code>defaultRenderStates</code> for ray and parabola pointers, <code>{}</code> for stylus pointers.
* @example <caption>Report the properties of a parabola pointer.</caption>
* var intersectEnd = {
* type: "sphere",
* dimensions: { x: 0.2, y: 0.2, z: 0.2 },
* solid: true,
* color: { red: 0, green: 255, blue: 0 },
* ignorePickIntersection: true
* };
* var intersectedPath = {
* color: { red: 0, green: 255, blue: 0 },
* };
* var searchEnd = {
* type: "sphere",
* dimensions: { x: 0.2, y: 0.2, z: 0.2 },
* solid: true,
* color: { red: 255, green: 0, blue: 0 },
* ignorePickIntersection: true
* };
* var searchPath = {
* color: { red: 255, green: 0, blue: 0 },
* };
*
* var renderStates = [{ name: "example", path: intersectedPath, end: intersectEnd }];
* var defaultRenderStates = [{ name: "example", distance: 20.0, path: searchPath, end: searchEnd }];
*
* // Create the pointer.
* var parabolaPointer = Pointers.createPointer(PickType.Parabola, {
* joint: "_CAMERA_RELATIVE_CONTROLLER_LEFTHAND",
* filter: Picks.PICK_LOCAL_ENTITIES | Picks.PICK_DOMAIN_ENTITIES | Picks.PICK_INCLUDE_NONCOLLIDABLE,
* renderStates: renderStates,
* defaultRenderStates: defaultRenderStates,
* enabled: true
* });
* Pointers.setRenderState(parabolaPointer, "example");
*
* // Report the pointer properties.
* Script.setTimeout(function () {
* var properties = Pointers.getPointerProperties(parabolaPointer);
* print("Pointer properties:" + JSON.stringify(properties));
* }, 500);
*
* // Tidy up.
* Script.scriptEnding.connect(function () {
* Pointers.removePointer(parabolaPointer);
* });
*/
Q_INVOKABLE QVariantMap getPointerProperties(unsigned int uid) const;
};

23
interface/src/raypick/RayPickScriptingInterface.h
View file

@ -107,7 +107,8 @@ public:
/**jsdoc
* Sets whether or not to use precision picking, i.e., whether to pick against precise meshes or coarse meshes.
* Sets whether or not a ray pick should use precision picking, i.e., whether it should pick against precise meshes or
* coarse meshes.
* @function RayPick.setPrecisionPicking
* @param {number} id - The ID of the ray pick.
* @param {boolean} precisionPicking - <code>true</code> to use precision picking, <code>false</code> to use coarse picking.
@ -115,7 +116,7 @@ public:
Q_INVOKABLE void setPrecisionPicking(unsigned int uid, bool precisionPicking);
/**jsdoc
* Sets a list of entity and avatar IDs to ignore during intersection.
* Sets a list of entity and avatar IDs that a ray pick should ignore during intersection.
* @function RayPick.setIgnoreItems
* @param {number} id - The ID of the ray pick.
* @param {Uuid[]} ignoreItems - The list of IDs to ignore.
@ -123,7 +124,8 @@ public:
Q_INVOKABLE void setIgnoreItems(unsigned int uid, const QScriptValue& ignoreEntities);
/**jsdoc
* Sets a list of entity IDs and/or avatar IDs to include during intersection, instead of intersecting with everything.
* Sets a list of entity and avatar IDs that a ray pick should include during intersection, instead of intersecting with
* everything.
* @function RayPick.setIncludeItems
* @param {number} id - The ID of the ray pick.
* @param {Uuid[]} includeItems - The list of IDs to include.
@ -132,9 +134,9 @@ public:
/**jsdoc
* Checks if a pick is associated with the left hand: a ray or parabola pick with joint set to
* <code>"_CONTROLLER_LEFTHAND"</code> or <code>"_CAMERA_RELATIVE_CONTROLLER_LEFTHAND"</code>, or a stylus pick with hand
* set to <code>0</code>.
* Checks if a pick is associated with the left hand: a ray or parabola pick with <code>joint</code> property set to
* <code>"_CONTROLLER_LEFTHAND"</code> or <code>"_CAMERA_RELATIVE_CONTROLLER_LEFTHAND"</code>, or a stylus pick with
* <code>hand</code> property set to <code>0</code>.
* @function RayPick.isLeftHand
* @param {number} id - The ID of the ray pick.
* @returns {boolean} <code>true</code> if the pick is associated with the left hand, <code>false</code> if it isn't.
@ -142,9 +144,9 @@ public:
Q_INVOKABLE bool isLeftHand(unsigned int uid);
/**jsdoc
* Checks if a pick is associated with the right hand: a ray or parabola pick with joint set to
* <code>"_CONTROLLER_RIGHTHAND"</code> or <code>"_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND"</code>, or a stylus pick with hand
* set to <code>1</code>.
* Checks if a pick is associated with the right hand: a ray or parabola pick with <code>joint</code> property set to
* <code>"_CONTROLLER_RIGHTHAND"</code> or <code>"_CAMERA_RELATIVE_CONTROLLER_RIGHTHAND"</code>, or a stylus pick with
* <code>hand</code> property set to <code>1</code>.
* @function RayPick.isRightHand
* @param {number} id - The ID of the ray pick.
* @returns {boolean} <code>true</code> if the pick is associated with the right hand, <code>false</code> if it isn't.
@ -152,7 +154,8 @@ public:
Q_INVOKABLE bool isRightHand(unsigned int uid);
/**jsdoc
* Checks if a pick is associated with the system mouse: a ray or parabola pick with joint set to <code>"Mouse"</code>.
* Checks if a pick is associated with the system mouse: a ray or parabola pick with <code>joint</code> property set to
* <code>"Mouse"</code>.
* @function RayPick.isMouse
* @param {number} id - The ID of the ray pick.
* @returns {boolean} <code>true</code> if the pick is associated with the system mouse, <code>false</code> if it isn't.