diff --git a/interface/src/Application.cpp b/interface/src/Application.cpp index 49e07ad658..36f1f4132a 100644 --- a/interface/src/Application.cpp +++ b/interface/src/Application.cpp @@ -693,10 +693,17 @@ private: * * * CameraFirstPersonnumbernumberThe camera is in first-person mode. - * + * Legacy first person camera mode. + * CameraFirstPersonLookAtnumbernumberThe camera is in first-person mode. + * Default first person camera mode. * CameraThirdPersonnumbernumberThe camera is in third-person mode. - * - * CameraFSMnumbernumberThe camera is in full screen mirror mode. + * Legacy third person camera mode. + * CameraLookAtnumbernumberThe camera is in third-person mode. + * Default third person camera mode. + * CameraFSMnumbernumberThe camera is in full screen mirror mode. + * Legacy "look at myself" behavior. + * CameraSelfienumbernumberThe camera is in selfie mode. + * Default "look at myself" camera mode. * CameraIndependentnumbernumberThe camera is in independent mode. * CameraEntitynumbernumberThe camera is in entity mode. * InHMDnumbernumberThe user is in HMD mode. diff --git a/interface/src/AvatarBookmarks.cpp b/interface/src/AvatarBookmarks.cpp index 8f666ddbfa..9204cd7514 100644 --- a/interface/src/AvatarBookmarks.cpp +++ b/interface/src/AvatarBookmarks.cpp @@ -187,7 +187,7 @@ void AvatarBookmarks::updateAvatarEntities(const QVariantList &avatarEntities) { * @property {number} avatarScale - The target scale of the avatar. * @property {Array>} [avatarEntites] - The avatar entities included with the * bookmark. - * @property {MyAvatar.AttachmentData[]} [attachments] - The attachments included with the bookmark. + * @property {AttachmentData[]} [attachments] - The attachments included with the bookmark. *

Deprecated: Use avatar entities instead. */ diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index fc857bb11c..9b9bc2d9df 100644 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -148,21 +148,21 @@ class MyAvatar : public Avatar { * size in the virtual world. Read-only. * @property {boolean} hasPriority - true if the avatar is in a "hero" zone, false if it isn't. * Read-only. - * @property {boolean} hasScriptedBlendshapes=false - true if blend shapes are controlled by scripted actions, - * otherwise false. Set this to true before using the {@link MyAvatar.setBlendshape} method, + * @property {boolean} hasScriptedBlendshapes=false - true if blend shapes are controlled by scripted actions, + * otherwise false. Set this to true before using the {@link MyAvatar.setBlendshape} method, * and set back to false after you no longer want scripted control over the blend shapes. - *

Note: This property will automatically be set to true if the Controller system has valid facial - * blend shape actions.

- * @property {boolean} hasProceduralBlinkFaceMovement=true - true if avatars blink automatically by animating - * facial blend shapes, false if automatic blinking is disabled. Set this property to false if - * you wish to fully control the blink facial blend shapes via the {@link MyAvatar.setBlendshape} method. - * @property {boolean} hasProceduralEyeFaceMovement=true - true if the facial blend shapes for an avatar's eyes - * adjust automatically as the eyes move, false if this automatic movement is disabled. Set this property - * to true to prevent the iris from being obscured by the upper or lower lids. Set this property to - * false if you wish to fully control the eye blend shapes via the {@link MyAvatar.setBlendshape} method. - * @property {boolean} hasAudioEnabledFaceMovement=true - true if the avatar's mouth blend shapes animate - * automatically based on detected microphone input, false if this automatic movement is disabled. Set - * this property to false if you wish to fully control the mouth facial blend shapes via the + *

Note: This property will automatically be set to true if the controller system has + * valid facial blend shape actions.

+ * @property {boolean} hasProceduralBlinkFaceMovement=true - true if avatars blink automatically by animating + * facial blend shapes, false if automatic blinking is disabled. Set this property to false + * to fully control the blink facial blend shapes via the {@link MyAvatar.setBlendshape} method. + * @property {boolean} hasProceduralEyeFaceMovement=true - true if the facial blend shapes for an avatar's eyes + * adjust automatically as the eyes move, false if this automatic movement is disabled. Set this property + * to true to prevent the iris from being obscured by the upper or lower lids. Set this property to + * false to fully control the eye blend shapes via the {@link MyAvatar.setBlendshape} method. + * @property {boolean} hasAudioEnabledFaceMovement=true - true if the avatar's mouth blend shapes animate + * automatically based on detected microphone input, false if this automatic movement is disabled. Set + * this property to false to fully control the mouth facial blend shapes via the * {@link MyAvatar.setBlendshape} method. * * @comment IMPORTANT: This group of properties is copied from Avatar.h; they should NOT be edited here. @@ -286,9 +286,9 @@ class MyAvatar : public Avatar { * @property {number} isInSittingState - true if the user wearing the HMD is determined to be sitting * (avatar leaning is disabled, recentering is enabled), false if the user wearing the HMD is * determined to be standing (avatar leaning is enabled, and avatar recenters if it leans too far). - * If userRecenterModel == 2 (i.e., auto) the property value automatically updates as the user sits + * If userRecenterModel == 2 (i.e., "auto") the property value automatically updates as the user sits * or stands, unless isSitStandStateLocked == true. Setting the property value overrides the current - * siting / standing state, which is updated when the user next sits or stands unless + * sitting / standing state, which is updated when the user next sits or stands unless * isSitStandStateLocked == true. * @property {boolean} isSitStandStateLocked - true to lock the avatar sitting/standing state, i.e., use this * to disable automatically changing state. @@ -321,10 +321,7 @@ class MyAvatar : public Avatar { * @borrows Avatar.setAttachmentsVariant as setAttachmentsVariant * @borrows Avatar.updateAvatarEntity as updateAvatarEntity * @borrows Avatar.clearAvatarEntity as clearAvatarEntity - * @borrows Avatar.hasScriptedBlendshapes as hasScriptedBlendshapes - * @borrows Avatar.hasProceduralBlinkFaceMovement as hasProceduralBlinkFaceMovement - * @borrows Avatar.hasProceduralEyeFaceMovement as hasProceduralEyeFaceMovement - * @borrows Avatar.hasAudioEnabledFaceMovement as hasAudioEnabledFaceMovement + * @borrows Avatar.setForceFaceTrackerConnected as setForceFaceTrackerConnected * @borrows Avatar.setSkeletonModelURL as setSkeletonModelURL * @borrows Avatar.getAttachmentData as getAttachmentData * @borrows Avatar.setAttachmentData as setAttachmentData @@ -530,7 +527,7 @@ public: * 0ForceSitAssumes the user is seated in the real world. Disables avatar * leaning regardless of what the avatar is doing in the virtual world (i.e., avatar always recenters). * 1ForceStandAssumes the user is standing in the real world. Enables avatar - * leaning regardless of what the avatar is doing in the virtual world (i.e. avatar leans, then if leans too far it + * leaning regardless of what the avatar is doing in the virtual world (i.e., avatar leans, then if leans too far it * recenters). * 2AutoInterface detects when the user is standing or seated in the real world. * Avatar leaning is disabled when the user is sitting (i.e., avatar always recenters), and avatar leaning is enabled @@ -657,7 +654,7 @@ public: *

Note: When using pre-built animation data, it's critical that the joint orientation of the source animation and target * rig are equivalent, since the animation data applies absolute values onto the joints. If the orientations are different, * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see - * Avatar Standards.

+ * Avatar Standards.

* @function MyAvatar.overrideAnimation * @param {string} url - The URL to the animation file. Animation files may be in glTF or FBX format, but only need to * contain the avatar skeleton and animation data. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs @@ -765,7 +762,7 @@ public: *

Note: When using pre-built animation data, it's critical that the joint orientation of the source animation and target * rig are equivalent, since the animation data applies absolute values onto the joints. If the orientations are different, * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see - * Avatar Standards. + * Avatar Standards. * @function MyAvatar.overrideRoleAnimation * @param {string} role - The animation role to override * @param {string} url - The URL to the animation file. Animation files need to be in glTF or FBX format, but only need to @@ -1186,7 +1183,7 @@ public: /**jsdoc * Gets information on the avatar your avatar is currently looking at. * @function MyAvatar.getTargetAvatar - * @returns {AvatarData} Information on the avatar being looked at. + * @returns {ScriptAvatar} Information on the avatar being looked at, null if no avatar is being looked at. */ // FIXME: The return type doesn't have a conversion to a script value so the function always returns undefined in // JavaScript. Note: When fixed, JSDoc is needed for the return type. @@ -1795,56 +1792,57 @@ public: void prepareAvatarEntityDataForReload(); /**jsdoc - * Turns the avatar's head until it faces the target point within a +90/-90 degree range. - * Once this method is called, API calls will have full control of the head for a limited time. - * If this method is not called for two seconds, the engine will regain control of the head. - * @function MyAvatar.setHeadLookAt - * @param {Vec3} lookAtTarget - The target point in world coordinates. - */ + * Turns the avatar's head until it faces the target point within a +90/-90 degree range. + * Once this method is called, API calls will have full control of the head for a limited time. + * If this method is not called for 2 seconds, the engine will regain control of the head. + * @function MyAvatar.setHeadLookAt + * @param {Vec3} lookAtTarget - The target point in world coordinates. + */ Q_INVOKABLE void setHeadLookAt(const glm::vec3& lookAtTarget); /**jsdoc - * Returns the current target point of the head's look direction in world coordinates. - * @function MyAvatar.getHeadLookAt - * @returns {Vec3} The head's "look at" target in world coordinates. - */ + * Returns the current target point of the head's look direction in world coordinates. + * @function MyAvatar.getHeadLookAt + * @returns {Vec3} The head's look-at target in world coordinates. + */ Q_INVOKABLE glm::vec3 getHeadLookAt() { return _lookAtCameraTarget; } /**jsdoc - * Returns control of the avatar's head to the engine, and releases control from API calls. - * @function MyAvatar.releaseHeadLookAtControl - */ + * Returns control of the avatar's head to the engine, and releases control from API calls. + * @function MyAvatar.releaseHeadLookAtControl + */ Q_INVOKABLE void releaseHeadLookAtControl(); /**jsdoc - * Forces the avatar's eyes to look at a specified location. Once this method is called, API calls - * have full control of the eyes for a limited time. If this method is not called for two seconds, - * the engine regains control of the eyes. - * @function MyAvatar.setEyesLookAt - * @param {Vec3} lookAtTarget - The target point in world coordinates. - */ + * Forces the avatar's eyes to look at a specified location. Once this method is called, API calls + * have full control of the eyes for a limited time. If this method is not called for two seconds, + * the engine regains control of the eyes. + * @function MyAvatar.setEyesLookAt + * @param {Vec3} lookAtTarget - The target point in world coordinates. + */ Q_INVOKABLE void setEyesLookAt(const glm::vec3& lookAtTarget); /**jsdoc - * Returns the current target point of the eyes look direction in world coordinates. - * @function MyAvatar.getEyesLookAt - * @returns {Vec3} The eyes' "look at" target in world coordinates. - */ + * Returns the current target point of the eyes look direction in world coordinates. + * @function MyAvatar.getEyesLookAt + * @returns {Vec3} The eyes' look-at target in world coordinates. + */ Q_INVOKABLE glm::vec3 getEyesLookAt() { return _eyesLookAtTarget.get(); } /**jsdoc - * Returns control of the avatar's eyes to the engine, and releases control from API calls. - * @function MyAvatar.releaseEyesLookAtControl - */ + * Returns control of the avatar's eyes to the engine, and releases control from API calls. + * @function MyAvatar.releaseEyesLookAtControl + */ Q_INVOKABLE void releaseEyesLookAtControl(); /**jsdoc - * Aims the pointing directional blending towards the provided target point. The "point" reaction should be triggered - * before using this method with the code MyAvatar.beginReaction("point"). - * @function MyAvatar.setPointAt - * @param {Vec3} pointAtTarget - The target point in world coordinates. - * @returns {boolean} true if the target point lays in front of the avatar, false if it doesn't. - */ + * Sets the point-at target for the "point" reaction that may be started with {@link MyAvatar.beginReaction}. + * The point-at target is set only if it is in front of the avatar. + *

Note: The "point" reaction should be started before calling this method.

+ * @function MyAvatar.setPointAt + * @param {Vec3} pointAtTarget - The target to point at, in world coordinates. + * @returns {boolean} true if the target point was set, false if it wasn't. + */ Q_INVOKABLE bool setPointAt(const glm::vec3& pointAtTarget); glm::quat getLookAtRotation() { return _lookAtYaw * _lookAtPitch; } @@ -1928,7 +1926,7 @@ public: * @param {boolean} isActive - true if flow simulation is enabled on the joint, false if it isn't. * @param {boolean} isCollidable - true to enable collisions in the flow simulation, false to * disable. - * @param {Object} [physicsConfig>] - Physics configurations for particular entity + * @param {Object} [physicsConfig] - Physics configurations for particular entity * and avatar joints. * @param {Object} [collisionsConfig] - Collision configurations for particular * entity and avatar joints. @@ -1952,8 +1950,8 @@ public: /**jsdoc * Starts a sitting action for the avatar. * @function MyAvatar.beginSit - * @param {Vec3} position - The point in space where the avatar will sit. - * @param {Quat} rotation - Initial absolute orientation of the avatar once is seated. + * @param {Vec3} position - The position where the avatar should sit. + * @param {Quat} rotation - The initial orientation of the seated avatar. */ Q_INVOKABLE void beginSit(const glm::vec3& position, const glm::quat& rotation); @@ -1961,15 +1959,14 @@ public: * Ends a sitting action for the avatar. * @function MyAvatar.endSit * @param {Vec3} position - The position of the avatar when standing up. - * @param {Quat} rotation - The absolute rotation of the avatar once the sitting action ends. + * @param {Quat} rotation - The orientation of the avatar when standing up. */ Q_INVOKABLE void endSit(const glm::vec3& position, const glm::quat& rotation); /**jsdoc - * Gets whether the avatar is in a seated pose. The seated pose is set by calling the - * MyAvatar::beginSit method. + * Gets whether the avatar is in a seated pose. The seated pose is set by calling {@link MyAvatar.beginSit}. * @function MyAvatar.isSeated - * @returns {boolean} true if the avatar is in a seated pose. + * @returns {boolean} true if the avatar is in a seated pose, false if it isn't. */ Q_INVOKABLE bool isSeated() { return _characterController.getSeated(); } @@ -2072,8 +2069,8 @@ public slots: * @param {boolean} [hasOrientation=false] - Set to true to set the orientation of the avatar. * @param {Quat} [orientation=Quat.IDENTITY] - The new orientation for the avatar. * @param {boolean} [shouldFaceLocation=false] - Set to true to position the avatar a short distance away from - * @param {boolean} [withSafeLanding=true] - Set to false MyAvatar::safeLanding will not be called (used when teleporting). * the new position and orientate the avatar to face the position. + * @param {boolean} [withSafeLanding=true] - Set to false to disable safe landing when teleporting. */ void goToLocation(const glm::vec3& newPosition, bool hasOrientation = false, const glm::quat& newOrientation = glm::quat(), @@ -2348,43 +2345,52 @@ public slots: virtual void setModelScale(float scale) override; /**jsdoc - * MyAvatar.getTriggerReactions - * Returns a list of reactions names that can be triggered using MyAvatar.triggerReaction(). - * @returns {string[]} Array of reaction names. + * Gets the list of reactions names that can be triggered using {@link MyAvatar.triggerReaction}. + *

See also: {@link MyAvatar.getBeginEndReactions}. + * @function MyAvatar.getTriggerReactions + * @returns {string[]} List of reaction names that can be triggered using {@link MyAvatar.triggerReaction}. + * @example List the available trigger reactions. + * print("Trigger reactions:", JSON.stringify(MyAvatar.getTriggerReactions())); */ QStringList getTriggerReactions() const; /**jsdoc - * MyAvatar.getBeginReactions - * Returns a list of reactions names that can be enabled using MyAvatar.beginReaction() and MyAvatar.endReaction(). - * @returns {string[]} Array of reaction names. + * Gets the list of reactions names that can be enabled using {@link MyAvatar.beginReaction} and + * {@link MyAvatar.endReaction}. + *

See also: {@link MyAvatar.getTriggerReactions}. + * @function MyAvatar.getBeginEndReactions + * @returns {string[]} List of reaction names that can be enabled using {@link MyAvatar.beginReaction} and + * {@link MyAvatar.endReaction}. + * @example List the available begin-end reactions. + * print("Begin-end reactions:", JSON.stringify(MyAvatar.getBeginEndReactions())); */ QStringList getBeginEndReactions() const; /**jsdoc - * MyAvatar.triggerReaction - * Plays the given reaction on the avatar, once the reaction is complete it will automatically complete. Only reaction names returned from MyAvatar.getTriggerReactions() are available. - * @param {string} reactionName - reaction name - * @returns {bool} false if the given reaction is not supported. + * Plays a reaction on the avatar. Once the reaction is complete it will stop playing. + *

Only reaction names returned by {@link MyAvatar.getTriggerReactions} are available.

+ * @function MyAvatar.triggerReaction + * @param {string} reactionName - The reaction to trigger. + * @returns {boolean} true if the reaction was played, false if the reaction is not supported. */ bool triggerReaction(QString reactionName); /**jsdoc - * MyAvatar.beginReaction - * Plays the given reaction on the avatar. The avatar will continue to play the reaction until stopped via the MyAvatar.endReaction() call or superseeded by another reaction. - * Only reaction names returned from MyAvatar.getBeginEndReactions() are available. - * NOTE: the caller is responsible for calling the corresponding MyAvatar.endReaction(), otherwise the avatar might become stuck in the reaction forever. - * @param {string} reactionName - reaction name - * @returns {bool} false if the given reaction is not supported. + * Starts playing a reaction on the avatar. The reaction will continue to play until stopped using + * {@link MyAvatar.endReaction} or superseded by another reaction. + *

Only reactions returned by {@link MyAvatar.getBeginEndReactions} are available.

+ * @function MyAvatar.beginReaction + * @param {string} reactionName - The reaction to start playing. + * @returns {boolean} true if the reaction was started, false if the reaction is not supported. */ bool beginReaction(QString reactionName); /**jsdoc - * MyAvatar.endReaction - * Used to stop a given reaction that was started via MyAvatar.beginReaction(). - * @param {string} reactionName - reaction name - * @returns {bool} false if the given reaction is not supported. + * Stops playing a reaction that was started using {@link MyAvatar.beginReaction}. + * @function MyAvatar.endReaction + * @param {string} reactionName - The reaction to stop playing. + * @returns {boolean} true if the reaction was stopped, false if the reaction is not supported. */ bool endReaction(QString reactionName); diff --git a/interface/src/raypick/PickScriptingInterface.h b/interface/src/raypick/PickScriptingInterface.h index 6319aeb01b..58ed3326ec 100644 --- a/interface/src/raypick/PickScriptingInterface.h +++ b/interface/src/raypick/PickScriptingInterface.h @@ -52,8 +52,9 @@ * Read-only. *

Warning: Not yet implemented.

* - * @property {FilterFlags} PICK_BYPASS_IGNORE - Allows pick to intersect entities even when their ignorePickIntersection property is 'true'. - * For debug purposes. Read-only. + * @property {FilterFlags} PICK_BYPASS_IGNORE - Allows pick to intersect entities even when their + * ignorePickIntersection property value is true. For debug purposes. + * Read-only. * * @property {IntersectionType} INTERSECTED_NONE - Intersected nothing. Read-only. * @property {IntersectionType} INTERSECTED_ENTITY - Intersected an entity. Read-only. diff --git a/interface/src/raypick/PointerScriptingInterface.h b/interface/src/raypick/PointerScriptingInterface.h index 4e59e53b06..555136e7a7 100644 --- a/interface/src/raypick/PointerScriptingInterface.h +++ b/interface/src/raypick/PointerScriptingInterface.h @@ -167,7 +167,7 @@ public: * of the pointer, see {@link Pointers.getPointerProperties}. * @function Pointers.getPointerScriptParameters * @param {number} id - The ID of the pointer. - * @returns {Pointers.RayPointerProperties|Picks.ParabolaPointerProperties|Picks.StylusPointerProperties} + * @returns {Pointers.RayPointerProperties|Pointers.ParabolaPointerProperties|Pointers.StylusPointerProperties} * Script-provided properties, per the pointer type. */ Q_INVOKABLE QVariantMap getPointerScriptParameters(unsigned int uid) const; diff --git a/interface/src/scripting/DesktopScriptingInterface.cpp b/interface/src/scripting/DesktopScriptingInterface.cpp index ae4af48cd6..f78f7853ca 100644 --- a/interface/src/scripting/DesktopScriptingInterface.cpp +++ b/interface/src/scripting/DesktopScriptingInterface.cpp @@ -30,21 +30,6 @@ * @property {InteractiveWindow.DockArea} LEFT - Dock to the left edge of the Interface window. * @property {InteractiveWindow.DockArea} RIGHT - Dock to the right edge of the Interface window. */ -/**jsdoc - *

A docking location of an InteractiveWindow.

- * - * - * - * - * - * - * - * - * - * - *
ValueNameDescription
0TOPDock to the top edge of the Interface window.
1BOTTOMDock to the bottom edge of the Interface window.
2LEFTDock to the left edge of the Interface window.
3RIGHTDock to the right edge of the Interface window.
- * @typedef {number} InteractiveWindow.DockArea - */ static const QVariantMap DOCK_AREA { { "TOP", DockArea::TOP }, { "BOTTOM", DockArea::BOTTOM }, @@ -53,13 +38,17 @@ static const QVariantMap DOCK_AREA { }; /**jsdoc - * The possible "relative position anchors" of an InteractiveWindow. Used when defining the `relativePosition` property of an `InteractiveWindow`. + * The possible relative position anchors of an InteractiveWindow relative to the Interface window. * @typedef {object} InteractiveWindow.RelativePositionAnchors - * @property {InteractiveWindow.RelativePositionAnchor} NO_ANCHOR - Specifies that the position of the `InteractiveWindow` will not be relative to any part of the Interface window. - * @property {InteractiveWindow.RelativePositionAnchor} TOP_LEFT - Specifies that the `relativePosition` of the `InteractiveWindow` will be offset from the top left of the Interface window. - * @property {InteractiveWindow.RelativePositionAnchor} TOP_RIGHT - Specifies that the `relativePosition` of the `InteractiveWindow` will be offset from the top right of the Interface window. - * @property {InteractiveWindow.RelativePositionAnchor} BOTTOM_RIGHT - Specifies that the `relativePosition` of the `InteractiveWindow` will be offset from the bottom right of the Interface window. - * @property {InteractiveWindow.RelativePositionAnchor} BOTTOM_LEFT - Specifies that the `relativePosition` of the `InteractiveWindow` will be offset from the bottom left of the Interface window. + * @property {InteractiveWindow.RelativePositionAnchor} NO_ANCHOR - Position is not relative to any part of the Interface + * window. + * @property {InteractiveWindow.RelativePositionAnchor} TOP_LEFT - Position is offset from the top left of the Interface window. + * @property {InteractiveWindow.RelativePositionAnchor} TOP_RIGHT - Position is offset from the top right of the Interface + * window. + * @property {InteractiveWindow.RelativePositionAnchor} BOTTOM_RIGHT - Position offset from the bottom right of the Interface + * window. + * @property {InteractiveWindow.RelativePositionAnchor} BOTTOM_LEFT - Position is offset from the bottom left of the Interface + * window. */ static const QVariantMap RELATIVE_POSITION_ANCHOR { { "NO_ANCHOR", RelativePositionAnchor::NO_ANCHOR }, @@ -89,21 +78,6 @@ int DesktopScriptingInterface::getHeight() { * @property {InteractiveWindow.PresentationMode} NATIVE - The window is displayed separately from the Interface window, as its * own separate window. */ -/**jsdoc - *

A display mode for an InteractiveWindow.

- * - * - * - * - * - * - * - * - *
ValueNameDescription
0VIRTUALThe window is displayed inside Interface: in the desktop window in - * desktop mode or on the HUD surface in HMD mode.
1NATIVEThe window is displayed separately from the Interface window, as its - * own separate window.
- * @typedef {number} InteractiveWindow.PresentationMode - */ QVariantMap DesktopScriptingInterface::getPresentationMode() { static QVariantMap presentationModes { { "VIRTUAL", Virtual }, diff --git a/interface/src/scripting/DesktopScriptingInterface.h b/interface/src/scripting/DesktopScriptingInterface.h index e75bd571e8..e57d7a6805 100644 --- a/interface/src/scripting/DesktopScriptingInterface.h +++ b/interface/src/scripting/DesktopScriptingInterface.h @@ -42,8 +42,8 @@ * @property {InteractiveWindow.DockAreas} DockArea - The possible docking locations of an {@link InteractiveWindow}: top, * bottom, left, or right of the Interface window. * Read-only. - * @property {InteractiveWindow.RelativePositionAnchors} RelativePositionAnchor - The possible "relative position anchors" for an {@link InteractiveWindow}: top left, - * top right, bottom right, or bottom left of the Interface window. + * @property {InteractiveWindow.RelativePositionAnchors} RelativePositionAnchor - The possible relative position anchors for an + * {@link InteractiveWindow}: none, top left, top right, bottom right, or bottom left of the Interface window. * Read-only. */ class DesktopScriptingInterface : public QObject, public Dependency { @@ -84,7 +84,7 @@ public: * @param {string} url - The QML file that specifies the window content. The QML file can use a WebView * control (defined by "WebView.qml" included in the Interface install) to embed an HTML web page (complete with * EventBridge object). - * @param {InteractiveWindow.Properties} [properties] - Initial window properties. + * @param {InteractiveWindow.WindowProperties} [properties] - Initial window properties. * @returns {InteractiveWindow} A new window object. * @example Open a dialog in its own window separate from Interface. * var nativeWindow = Desktop.createWindow(Script.resourcesPath() + 'qml/OverlayWindowTest.qml', { diff --git a/interface/src/scripting/WindowScriptingInterface.h b/interface/src/scripting/WindowScriptingInterface.h index f3e9dea45f..bf39073db1 100644 --- a/interface/src/scripting/WindowScriptingInterface.h +++ b/interface/src/scripting/WindowScriptingInterface.h @@ -818,8 +818,12 @@ signals: /**jsdoc * Triggered when "minimized" state of the Interface window changes. * @function Window.minimizedChanged - * @param {bool} isMinimized - true if the Interface window is now minimized; false otherwise. + * @param {boolean} isMinimized - true if the Interface window is minimized, false if it isn't. * @returns {Signal} + * @example Report the "minimized" state of the Interface window when it changes. + * function onWindowMinimizedChanged(minimized) { + * print("Window minimized: " + minimized); + * } * * Window.minimizedChanged.connect(onWindowMinimizedChanged); */ diff --git a/interface/src/ui/InteractiveWindow.cpp b/interface/src/ui/InteractiveWindow.cpp index 6cc26e2409..2acac2c529 100644 --- a/interface/src/ui/InteractiveWindow.cpp +++ b/interface/src/ui/InteractiveWindow.cpp @@ -129,8 +129,8 @@ void InteractiveWindow::emitMainWindowResizeEvent() { } /**jsdoc - * A set of properties used when creating an InteractiveWindow. - * @typedef {object} InteractiveWindow.Properties + * Property values used when creating an InteractiveWindow. + * @typedef {object} InteractiveWindow.WindowProperties * @property {string} [title="InteractiveWindow] - The title of the window. * @property {Vec2} [position] - The initial position of the window, in pixels. * @property {Vec2} [size] - The initial size of the window, in pixels @@ -142,13 +142,36 @@ void InteractiveWindow::emitMainWindowResizeEvent() { * @property {InteractiveWindow.PresentationWindowInfo} [presentationWindowInfo] - Controls how a NATIVE window is * displayed. If used, the window is docked to the specified edge of the Interface window, otherwise the window is * displayed as its own separate window. - * @property {InteractiveWindow.AdditionalFlags} [additionalFlags=0] - Window behavior flags in addition to "native window flags" (minimize/maximize/close), - * set at window creation. Possible flag values are provided as {@link Desktop|Desktop.ALWAYS_ON_TOP} and {@link Desktop|Desktop.CLOSE_BUTTON_HIDES}. - * Additional flag values can be found on Qt's website at https://doc.qt.io/qt-5/qt.html#WindowType-enum. - * @property {InteractiveWindow.OverrideFlags} [overrideFlags=0] - Window behavior flags instead of the default window flags. - * Set at window creation. Possible flag values are provided as {@link Desktop|Desktop.ALWAYS_ON_TOP} and {@link Desktop|Desktop.CLOSE_BUTTON_HIDES}. - * Additional flag values can be found on Qt's website at https://doc.qt.io/qt-5/qt.html#WindowType-enum. + * @property {InteractiveWindow.Flags} [additionalFlags=0] - Customizes window behavior. + * @property {InteractiveWindow.OverrideFlags} [overrideFlags=0] - Customizes window controls. + + * @property {InteractiveWindow.RelativePositionAnchor} [relativePositionAnchor] - he anchor for the + * relativePosition, if used. + * @property {Vec2} [relativePosition] - The position of the window, relative to the relativePositionAnchor, in + * pixels. Excludes the window frame. + * @property {boolean} [isFullScreenWindow] - true to make the window full screen. */ +/**jsdoc + *

A set of flags customizing InteractiveWindow controls. The value is constructed by using the | + * (bitwise OR) operator on the individual flag values..

+ * + * + * + * + * + * + * + *
ValueNameDescription
0x00000001WindowDisplays the window as a window rather than a dialog.
0x00001000WindowTitleHintAdds a title bar. + *
0x00002000WindowSystemMenuHintAdds a window system menu. + *
0x00004000WindowMinimizeButtonHintAdds a minimize button. + *
0x00008000WindowMaximizeButtonHintAdds a maximize button. + *
0x00040000WindowStaysOnTopHintThe window stays on top of other windows. + * Not used on Windows. + *
0x08000000WindowCloseButtonHintAdds a close button. + *
+ * @typedef {number} InteractiveWindow.OverrideFlags + */ +// OverrideFlags is per InteractiveWindow.qml. InteractiveWindow::InteractiveWindow(const QString& sourceUrl, const QVariantMap& properties, bool restricted) { InteractiveWindowPresentationMode presentationMode = InteractiveWindowPresentationMode::Native; diff --git a/interface/src/ui/InteractiveWindow.h b/interface/src/ui/InteractiveWindow.h index 1198ce8ee9..7c8897059f 100644 --- a/interface/src/ui/InteractiveWindow.h +++ b/interface/src/ui/InteractiveWindow.h @@ -76,12 +76,42 @@ namespace InteractiveWindowEnums { }; Q_ENUM_NS(InteractiveWindowFlags); + /**jsdoc + *

A display mode for an InteractiveWindow.

+ * + * + * + * + * + * + * + * + *
ValueNameDescription
0VIRTUALThe window is displayed inside Interface: in the desktop window in + * desktop mode or on the HUD surface in HMD mode.
1NATIVEThe window is displayed separately from the Interface window, as its + * own separate window.
+ * @typedef {number} InteractiveWindow.PresentationMode + */ enum InteractiveWindowPresentationMode { Virtual, Native }; Q_ENUM_NS(InteractiveWindowPresentationMode); + /**jsdoc + *

A docking location of an InteractiveWindow.

+ * + * + * + * + * + * + * + * + * + * + *
ValueNameDescription
0TOPDock to the top edge of the Interface window.
1BOTTOMDock to the bottom edge of the Interface window.
2LEFTDock to the left edge of the Interface window.
3RIGHTDock to the right edge of the Interface window.
+ * @typedef {number} InteractiveWindow.DockArea + */ enum DockArea { TOP, BOTTOM, @@ -90,6 +120,24 @@ namespace InteractiveWindowEnums { }; Q_ENUM_NS(DockArea); + /**jsdoc + *

The anchor for a relative position of an InteractiveWindow.

+ * + * + * + * + * + * + * + * + * + * + * + *
ValueNameDescription
0NO_ANCHORPosition is not relative to any part of the Interface window.
1TOP_LEFTPosition is offset from the top left of the Interface window.
2TOP_RIGHTPosition is offset from the top right of the Interface window.
3BOTTOM_RIGHTPosition offset from the bottom right of the Interface + * window.
4BOTTOM_LEFFTPosition is offset from the bottom left of the Interface + * window.
+ * @typedef {number} InteractiveWindow.RelativePositionAnchor + */ enum RelativePositionAnchor { NO_ANCHOR, TOP_LEFT, @@ -117,7 +165,11 @@ using namespace InteractiveWindowEnums; * @hifi-avatar * * @property {string} title - The title of the window. - * @property {Vec2} position - The position of the window, in pixels. + * @property {Vec2} position - The absolute position of the window, in pixels. + * @property {InteractiveWindow.RelativePositionAnchor} relativePositionAnchor - The anchor for the + * relativePosition, if used. + * @property {Vec2} relativePosition - The position of the window, relative to the relativePositionAnchor, in + * pixels. Excludes the window frame. * @property {Vec2} size - The size of the window, in pixels. * @property {boolean} visible - true if the window is visible, false if it isn't. * @property {InteractiveWindow.PresentationMode} presentationMode - The presentation mode of the window: diff --git a/libraries/avatars-renderer/src/avatars-renderer/Avatar.cpp b/libraries/avatars-renderer/src/avatars-renderer/Avatar.cpp index d0ab314edf..a9e16e9ff1 100644 --- a/libraries/avatars-renderer/src/avatars-renderer/Avatar.cpp +++ b/libraries/avatars-renderer/src/avatars-renderer/Avatar.cpp @@ -1920,6 +1920,13 @@ void Avatar::setParentJointIndex(quint16 parentJointIndex) { } } +/**jsdoc + * Information about a joint in an avatar's skeleton hierarchy. + * @typedef {object} SkeletonJoint + * @property {string} name - Joint name. + * @property {number} index - Joint index. + * @property {number} parentIndex - Index of this joint's parent (-1 if no parent). + */ QList Avatar::getSkeleton() { SkeletonModelPointer skeletonModel = _skeletonModel; if (skeletonModel) { diff --git a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h index 9c57fa36ae..dcd4d00db0 100644 --- a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h +++ b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h @@ -207,7 +207,7 @@ public: /**jsdoc * Gets the default rotation of a joint (in the current avatar) relative to its parent. *

For information on the joint hierarchy used, see - * Avatar Standards.

+ * Avatar Standards.

* @function MyAvatar.getDefaultJointRotation * @param {number} index - The joint index. * @returns {Quat} The default rotation of the joint if the joint index is valid, otherwise {@link Quat(0)|Quat.IDENTITY}. @@ -218,7 +218,7 @@ public: * Gets the default translation of a joint (in the current avatar) relative to its parent, in model coordinates. *

Warning: These coordinates are not necessarily in meters.

*

For information on the joint hierarchy used, see - * Avatar Standards.

+ * Avatar Standards.

* @function MyAvatar.getDefaultJointTranslation * @param {number} index - The joint index. * @returns {Vec3} The default translation of the joint (in model coordinates) if the joint index is valid, otherwise @@ -480,14 +480,7 @@ public: /**jsdoc * Gets information on all the joints in the avatar's skeleton. * @function MyAvatar.getSkeleton - * @returns {MyAvatar.SkeletonJoint[]} Information about each joint in the avatar's skeleton. - */ - /**jsdoc - * Information about a single joint in an Avatar's skeleton hierarchy. - * @typedef {object} MyAvatar.SkeletonJoint - * @property {string} name - Joint name. - * @property {number} index - Joint index. - * @property {number} parentIndex - Index of this joint's parent (-1 if no parent). + * @returns {SkeletonJoint[]} Information about each joint in the avatar's skeleton. */ Q_INVOKABLE QList getSkeleton(); diff --git a/libraries/avatars-renderer/src/avatars-renderer/ScriptAvatar.h b/libraries/avatars-renderer/src/avatars-renderer/ScriptAvatar.h index 3bc98e72a0..3f8fc4f88b 100644 --- a/libraries/avatars-renderer/src/avatars-renderer/ScriptAvatar.h +++ b/libraries/avatars-renderer/src/avatars-renderer/ScriptAvatar.h @@ -16,6 +16,64 @@ #include "Avatar.h" +/**jsdoc + * Information about an avatar. + * + *

Created using {@link MyAvatar.getTargetAvatar} or {@link AvatarList.getAvatar}.

+ * + * @class ScriptAvatar + * @hideconstructor + * + * @hifi-interface + * @hifi-client-entity + * @hifi-avatar + * @hifi-assignment-client + * @hifi-server-entity + * + * @property {Vec3} position - The avatar's position. + * @property {number} scale - The target scale of the avatar without any restrictions on permissible values imposed by the + * domain. + * @property {Vec3} handPosition - A user-defined hand position, in world coordinates. The position moves with the avatar but + * is otherwise not used or changed by Interface. + * @property {number} bodyPitch - The pitch of the avatar's body, in degrees. + * @property {number} bodyYaw - The yaw of the avatar's body, in degrees. + * @property {number} bodyRoll - The roll of the avatar's body, in degrees. + * @property {Quat} orientation - The orientation of the avatar's body. + * @property {Quat} headOrientation - The orientation of the avatar's head. + * @property {number} headPitch - The pitch of the avatar's head relative to the body, in degrees. + * @property {number} headYaw - The yaw of the avatar's head relative to the body, in degrees. + * @property {number} headRoll - The roll of the avatar's head relative to the body, in degrees. + * + * @property {Vec3} velocity - The linear velocity of the avatar. + * @property {Vec3} angularVelocity - The angular velocity of the avatar. + * + * @property {Uuid} sessionUUID - The avatar's session ID. + * @property {string} displayName - The avatar's display name. + * @property {string} sessionDisplayName - The avatar's display name, sanitized and versioned, as defined by the avatar mixer. + * It is unique among all avatars present in the domain at the time. + * @property {boolean} isReplicated - Deprecated: This property is deprecated and will be + * removed. + * @property {boolean} lookAtSnappingEnabled - true if the avatar's eyes snap to look at another avatar's eyes + * when the other avatar is in the line of sight and also has lookAtSnappingEnabled == true. + * + * @property {string} skeletonModelURL - The avatar's FST file. + * @property {AttachmentData[]} attachmentData - Information on the avatar's attachments. + *

Deprecated: This property is deprecated and will be removed. Use avatar entities instead.

+ * @property {string[]} jointNames - The list of joints in the avatar model. + * + * @property {number} audioLoudness - The instantaneous loudness of the audio input that the avatar is injecting into the + * domain. + * @property {number} audioAverageLoudness - The rolling average loudness of the audio input that the avatar is injecting into + * the domain. + * + * @property {Mat4} sensorToWorldMatrix - The scale, rotation, and translation transform from the user's real world to the + * avatar's size, orientation, and position in the virtual world. + * @property {Mat4} controllerLeftHandMatrix - The rotation and translation of the left hand controller relative to the avatar. + * @property {Mat4} controllerRightHandMatrix - The rotation and translation of the right hand controller relative to the + * avatar. + * + * @property {Vec3} skeletonOffset - The rendering offset of the avatar. + */ class ScriptAvatar : public ScriptAvatarData { Q_OBJECT @@ -26,27 +84,138 @@ public: public slots: + /**jsdoc + * Gets the default rotation of a joint in the avatar relative to its parent. + *

For information on the joint hierarchy used, see + * Avatar Standards.

+ * @function ScriptAvatar.getDefaultJointRotation + * @param {number} index - The joint index. + * @returns {Quat} The default rotation of the joint if avatar data are available and the joint index is valid, otherwise + * {@link Quat(0)|Quat.IDENTITY}. + */ glm::quat getDefaultJointRotation(int index) const; + + /**jsdoc + * Gets the default translation of a joint in the avatar relative to its parent, in model coordinates. + *

Warning: These coordinates are not necessarily in meters.

+ *

For information on the joint hierarchy used, see + * Avatar Standards.

+ * @function ScriptAvatar.getDefaultJointTranslation + * @param {number} index - The joint index. + * @returns {Vec3} The default translation of the joint (in model coordinates) if avatar data are available and the joint + * index is valid, otherwise {@link Vec3(0)|Vec3.ZERO}. + */ glm::vec3 getDefaultJointTranslation(int index) const; + + /**jsdoc + * Gets the offset applied to the avatar for rendering. + * @function ScriptAvatar.getSkeletonOffset + * @returns {Vec3} The skeleton offset if avatar data are available, otherwise {@link Vec3(0)|Vec3.ZERO}. + */ glm::vec3 getSkeletonOffset() const; + + /**jsdoc + * Gets the position of a joint in the avatar. + * @function ScriptAvatar.getJointPosition + * @param {number} index - The index of the joint. + * @returns {Vec3} The position of the joint in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't + * available. + */ glm::vec3 getJointPosition(int index) const; + + /**jsdoc + * Gets the position of a joint in the current avatar. + * @function ScriptAvatar.getJointPosition + * @param {string} name - The name of the joint. + * @returns {Vec3} The position of the joint in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't + * available. + */ glm::vec3 getJointPosition(const QString& name) const; + + /**jsdoc + * Gets the position of the current avatar's neck in world coordinates. + * @function ScriptAvatar.getNeckPosition + * @returns {Vec3} The position of the neck in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't + * available. + */ glm::vec3 getNeckPosition() const; + + /**jsdoc + * Gets the current acceleration of the avatar. + * @function ScriptAvatar.getAcceleration + * @returns {Vec3} The current acceleration of the avatar, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't available.. + */ glm::vec3 getAcceleration() const; + + /**jsdoc + * Gets the ID of the entity of avatar that the avatar is parented to. + * @function ScriptAvatar.getParentID + * @returns {Uuid} The ID of the entity or avatar that the avatar is parented to. {@link Uuid(0)|Uuid.NULL} if not parented + * or avatar data aren't available. + */ QUuid getParentID() const; + + /**jsdoc + * Gets the joint of the entity or avatar that the avatar is parented to. + * @function ScriptAvatar.getParentJointIndex + * @returns {number} The joint of the entity or avatar that the avatar is parented to. 65535 or + * -1 if parented to the entity or avatar's position and orientation rather than a joint, or avatar data + * aren't available. + */ quint16 getParentJointIndex() const; + + /**jsdoc + * Gets information on all the joints in the avatar's skeleton. + * @function ScriptAvatar.getSkeleton + * @returns {SkeletonJoint[]} Information about each joint in the avatar's skeleton. + */ QVariantList getSkeleton() const; + + /**jsdoc + * @function ScriptAvatar.getSimulationRate + * @param {AvatarSimulationRate} [rateName=""] - Rate name. + * @returns {number} Simulation rate in Hz, or 0.0 if avatar data aren't available. + * @deprecated This function is deprecated and will be removed. + */ float getSimulationRate(const QString& rateName = QString("")) const; + + /**jsdoc + * Gets the position of the left palm in world coordinates. + * @function ScriptAvatar.getLeftPalmPosition + * @returns {Vec3} The position of the left palm in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't + * available. + */ glm::vec3 getLeftPalmPosition() const; + + /**jsdoc + * Gets the rotation of the left palm in world coordinates. + * @function ScriptAvatar.getLeftPalmRotation + * @returns {Quat} The rotation of the left palm in world coordinates, or {@link Quat(0)|Quat.IDENTITY} if the avatar data + * aren't available. + */ glm::quat getLeftPalmRotation() const; + + /**jsdoc + * Gets the position of the right palm in world coordinates. + * @function ScriptAvatar.getLeftPalmPosition + * @returns {Vec3} The position of the right palm in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't + * available. + */ glm::vec3 getRightPalmPosition() const; + + /**jsdoc + * Gets the rotation of the right palm in world coordinates. + * @function ScriptAvatar.getLeftPalmRotation + * @returns {Quat} The rotation of the right palm in world coordinates, or {@link Quat(0)|Quat.IDENTITY} if the avatar data + * aren't available. + */ glm::quat getRightPalmRotation() const; private: diff --git a/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index 981882bf98..24808b98bf 100755 --- a/libraries/avatars/src/AvatarData.h +++ b/libraries/avatars/src/AvatarData.h @@ -533,21 +533,21 @@ class AvatarData : public QObject, public SpatiallyNestable { * @property {boolean} hasPriority - true if the avatar is in a "hero" zone, false if it isn't. * Read-only. * @property {boolean} hasScriptedBlendshapes=false - true if blend shapes are controlled by scripted actions, - * otherwise false. Set this to true before using the {@link MyAvatar.setBlendshape} method, + * otherwise false. Set this to true before using the {@link Avatar.setBlendshape} method, * and set back to false after you no longer want scripted control over the blend shapes. - *

Note: This property will automatically be set to true if the Controller system has valid facial - * blend shape actions.

+ *

Note: This property will automatically be set to true if the controller system has + * valid facial blend shape actions.

* @property {boolean} hasProceduralBlinkFaceMovement=true - true if avatars blink automatically by animating - * facial blend shapes, false if automatic blinking is disabled. Set this property to false if - * you wish to fully control the blink facial blend shapes via the {@link MyAvatar.setBlendshape} method. + * facial blend shapes, false if automatic blinking is disabled. Set this property to false + * to fully control the blink facial blend shapes via the {@link Avatar.setBlendshape} method. * @property {boolean} hasProceduralEyeFaceMovement=true - true if the facial blend shapes for an avatar's eyes * adjust automatically as the eyes move, false if this automatic movement is disabled. Set this property * to true to prevent the iris from being obscured by the upper or lower lids. Set this property to - * false if you wish to fully control the eye blend shapes via the {@link MyAvatar.setBlendshape} method. + * false to fully control the eye blend shapes via the {@link Avatar.setBlendshape} method. * @property {boolean} hasAudioEnabledFaceMovement=true - true if the avatar's mouth blend shapes animate * automatically based on detected microphone input, false if this automatic movement is disabled. Set - * this property to false if you wish to fully control the mouth facial blend shapes via the - * {@link MyAvatar.setBlendshape} method. + * this property to false to fully control the mouth facial blend shapes via the + * {@link Avatar.setBlendshape} method. */ Q_PROPERTY(glm::vec3 position READ getWorldPosition WRITE setPositionViaScript) Q_PROPERTY(float scale READ getDomainLimitedScale WRITE setTargetScale) @@ -860,7 +860,7 @@ public: /**jsdoc * Gets the rotation of a joint relative to its parent. For information on the joint hierarchy used, see - * Avatar Standards. + * Avatar Standards. * @function Avatar.getJointRotation * @param {number} index - The index of the joint. * @returns {Quat} The rotation of the joint relative to its parent. @@ -871,7 +871,7 @@ public: * Gets the translation of a joint relative to its parent, in model coordinates. *

Warning: These coordinates are not necessarily in meters.

*

For information on the joint hierarchy used, see - * Avatar Standards.

+ * Avatar Standards.

* @function Avatar.getJointTranslation * @param {number} index - The index of the joint. * @returns {Vec3} The translation of the joint relative to its parent, in model coordinates. @@ -981,7 +981,7 @@ public: /**jsdoc * Gets the rotation of a joint relative to its parent. For information on the joint hierarchy used, see - * Avatar Standards. + * Avatar Standards. * @function Avatar.getJointRotation * @param {string} name - The name of the joint. * @returns {Quat} The rotation of the joint relative to its parent. @@ -996,7 +996,7 @@ public: * Gets the translation of a joint relative to its parent, in model coordinates. *

Warning: These coordinates are not necessarily in meters.

*

For information on the joint hierarchy used, see - * Avatar Standards.

+ * Avatar Standards.

* @function Avatar.getJointTranslation * @param {number} name - The name of the joint. * @returns {Vec3} The translation of the joint relative to its parent, in model coordinates. @@ -1134,8 +1134,8 @@ public: /**jsdoc * Sets the value of a blend shape to animate your avatar's face. In order for other users to see the resulting animations - * on your avatar's face, set {@link Avatar.hasScriptedBlendshapes} to true. When you are done using this API, - * set {@link Avatar.hasScriptedBlendshapes} back to false when the animation is complete. + * on your avatar's face, set hasScriptedBlendshapes to true. When you are done using this API, + * set hasScriptedBlendshapes back to false when the animation is complete. * @function Avatar.setBlendshape * @param {string} name - The name of the blendshape, per the * {@link https://docs.highfidelity.com/create/avatars/avatar-standards.html#blendshapes Avatar Standards}. @@ -1174,7 +1174,7 @@ public: /**jsdoc * @function Avatar.updateAvatarEntity * @param {Uuid} entityID - The entity ID. - * @param {Array.} entityData - Entity data. + * @param {ArrayBuffer} entityData - Entity data. * @deprecated This function is deprecated and will be removed. */ Q_INVOKABLE virtual void updateAvatarEntity(const QUuid& entityID, const QByteArray& entityData); @@ -1188,12 +1188,12 @@ public: Q_INVOKABLE virtual void clearAvatarEntity(const QUuid& entityID, bool requiresRemovalFromTree = true); /**jsdoc - *

Deprecated: This method is deprecated and will be removed.

- * Use Avatar.hasScriptedBlendshapes property instead. - * Enables blendshapes set using {@link Avatar.setBlendshape} or {@link MyAvatar.setBlendshape} to be transmitted to other + * Enables blend shapes set using {@link Avatar.setBlendshape} or {@link MyAvatar.setBlendshape} to be transmitted to other * users so that they can see the animation of your avatar's face. + *

Deprecated: This method is deprecated and will be removed. Use the + * Avatar.hasScriptedBlendshapes or MyAvatar.hasScriptedBlendshapes property instead.

* @function Avatar.setForceFaceTrackerConnected - * @param {boolean} connected - true to enable blendshape changes to be transmitted to other users, + * @param {boolean} connected - true to enable blend shape changes to be transmitted to other users, * false to disable. */ Q_INVOKABLE void setForceFaceTrackerConnected(bool connected) { setHasScriptedBlendshapes(connected); } @@ -1964,6 +1964,7 @@ Q_DECLARE_METATYPE(RayToAvatarIntersectionResult) QScriptValue RayToAvatarIntersectionResultToScriptValue(QScriptEngine* engine, const RayToAvatarIntersectionResult& results); void RayToAvatarIntersectionResultFromScriptValue(const QScriptValue& object, RayToAvatarIntersectionResult& results); +// No JSDoc because it's not provided as a type to the script engine. class ParabolaToAvatarIntersectionResult { public: bool intersects { false }; diff --git a/libraries/avatars/src/AvatarHashMap.h b/libraries/avatars/src/AvatarHashMap.h index c474353451..e12e5b4649 100644 --- a/libraries/avatars/src/AvatarHashMap.h +++ b/libraries/avatars/src/AvatarHashMap.h @@ -111,7 +111,7 @@ public: * Gets information about an avatar. * @function AvatarList.getAvatar * @param {Uuid} avatarID - The ID of the avatar. - * @returns {AvatarData} Information about the avatar. + * @returns {ScriptAvatar} Information about the avatar. */ // Null/Default-constructed QUuids will return MyAvatar Q_INVOKABLE virtual ScriptAvatarData* getAvatar(QUuid avatarID) { return new ScriptAvatarData(getAvatarBySessionID(avatarID)); } diff --git a/libraries/avatars/src/ScriptAvatarData.h b/libraries/avatars/src/ScriptAvatarData.h index 9c5c2c6918..7dcd7cc7e1 100644 --- a/libraries/avatars/src/ScriptAvatarData.h +++ b/libraries/avatars/src/ScriptAvatarData.h @@ -16,53 +16,6 @@ #include "AvatarData.h" -/**jsdoc - * Information about an avatar. - * @typedef {object} AvatarData - * @property {Vec3} position - The avatar's position. - * @property {number} scale - The target scale of the avatar without any restrictions on permissible values imposed by the - * domain. - * @property {Vec3} handPosition - A user-defined hand position, in world coordinates. The position moves with the avatar but - * is otherwise not used or changed by Interface. - * @property {number} bodyPitch - The pitch of the avatar's body, in degrees. - * @property {number} bodyYaw - The yaw of the avatar's body, in degrees. - * @property {number} bodyRoll - The roll of the avatar's body, in degrees. - * @property {Quat} orientation - The orientation of the avatar's body. - * @property {Quat} headOrientation - The orientation of the avatar's head. - * @property {number} headPitch - The pitch of the avatar's head relative to the body, in degrees. - * @property {number} headYaw - The yaw of the avatar's head relative to the body, in degrees. - * @property {number} headRoll - The roll of the avatar's head relative to the body, in degrees. - * - * @property {Vec3} velocity - The linear velocity of the avatar. - * @property {Vec3} angularVelocity - The angular velocity of the avatar. - * - * @property {Uuid} sessionUUID - The avatar's session ID. - * @property {string} displayName - The avatar's display name. - * @property {string} sessionDisplayName - The avatar's display name, sanitized and versioned, as defined by the avatar mixer. - * It is unique among all avatars present in the domain at the time. - * @property {boolean} isReplicated - Deprecated: This property is deprecated and will be - * removed. - * @property {boolean} lookAtSnappingEnabled - true if the avatar's eyes snap to look at another avatar's eyes - * when the other avatar is in the line of sight and also has lookAtSnappingEnabled == true. - * - * @property {string} skeletonModelURL - The avatar's FST file. - * @property {AttachmentData[]} attachmentData - Information on the avatar's attachments. - *

Deprecated: This property is deprecated and will be removed. Use avatar entities instead.

- * @property {string[]} jointNames - The list of joints in the current avatar model. - * - * @property {number} audioLoudness - The instantaneous loudness of the audio input that the avatar is injecting into the - * domain. - * @property {number} audioAverageLoudness - The rolling average loudness of the audio input that the avatar is injecting into - * the domain. - * - * @property {Mat4} sensorToWorldMatrix - The scale, rotation, and translation transform from the user's real world to the - * avatar's size, orientation, and position in the virtual world. - * @property {Mat4} controllerLeftHandMatrix - The rotation and translation of the left hand controller relative to the avatar. - * @property {Mat4} controllerRightHandMatrix - The rotation and translation of the right hand controller relative to the - * avatar. - * - * @property {boolean} hasPriority - true if the avatar is in a "hero" zone, false if it isn't. - */ class ScriptAvatarData : public QObject { Q_OBJECT @@ -153,16 +106,110 @@ public: // ATTACHMENT AND JOINT PROPERTIES // QString getSkeletonModelURLFromScript() const; + + /**jsdoc + * Gets the pointing state of the hands to control where the laser emanates from. If the right index finger is pointing, the + * laser emanates from the tip of that finger, otherwise it emanates from the palm. + * @function ScriptAvatar.getHandState + * @returns {HandState|number} The pointing state of the hand, or -1 if the avatar data aren't available. + */ Q_INVOKABLE char getHandState() const; + + /**jsdoc + * Gets the rotation of a joint relative to its parent. For information on the joint hierarchy used, see + * Avatar Standards. + * @function ScriptAvatar.getJointRotation + * @param {number} index - The index of the joint. + * @returns {Quat} The rotation of the joint relative to its parent, or {@link Quat(0)|Quat.IDENTITY} if the avatar data + * aren't available. + */ Q_INVOKABLE glm::quat getJointRotation(int index) const; + + /**jsdoc + * Gets the translation of a joint relative to its parent, in model coordinates. + *

Warning: These coordinates are not necessarily in meters.

+ *

For information on the joint hierarchy used, see + * Avatar Standards.

+ * @function ScriptAvatar.getJointTranslation + * @param {number} index - The index of the joint. + * @returns {Vec3} The translation of the joint relative to its parent, in model coordinates, or {@link Vec3(0)|Vec3.ZERO} + * if the avatar data aren't available. + */ Q_INVOKABLE glm::vec3 getJointTranslation(int index) const; + + /**jsdoc + * Gets the rotation of a joint relative to its parent. For information on the joint hierarchy used, see + * Avatar Standards. + * @function ScriptAvatar.getJointRotation + * @param {string} name - The name of the joint. + * @returns {Quat} The rotation of the joint relative to its parent, or {@link Quat(0)|Quat.IDENTITY} if the avatar data + * aren't available. + */ Q_INVOKABLE glm::quat getJointRotation(const QString& name) const; + + /**jsdoc + * Gets the translation of a joint relative to its parent, in model coordinates. + *

Warning: These coordinates are not necessarily in meters.

+ *

For information on the joint hierarchy used, see + * Avatar Standards.

+ * @function ScriptAvatar.getJointTranslation + * @param {number} name - The name of the joint. + * @returns {Vec3} The translation of the joint relative to its parent, in model coordinates, or {@link Vec3(0)|Vec3.ZERO} + * if the avatar data aren't available. + */ Q_INVOKABLE glm::vec3 getJointTranslation(const QString& name) const; + + /**jsdoc + * Gets the rotations of all joints in the avatar. Each joint's rotation is relative to its parent joint. + * @function ScriptAvatar.getJointRotations + * @returns {Quat[]} The rotations of all joints relative to each's parent, or [] if the avatar data aren't + * available. The values are in the same order as the array returned by {@link ScriptAvatar.getJointNames}. + */ Q_INVOKABLE QVector getJointRotations() const; + + /**jsdoc + * Gets the translations of all joints in the avatar. Each joint's translation is relative to its parent joint, in + * model coordinates. + *

Warning: These coordinates are not necessarily in meters.

+ * @function ScriptAvatar.getJointTranslations + * @returns {Vec3[]} The translations of all joints relative to each's parent, in model coordinates, or [] if + * the avatar data aren't available. The values are in the same order as the array returned by + * {@link ScriptAvatar.getJointNames}. + */ Q_INVOKABLE QVector getJointTranslations() const; + + /**jsdoc + * Checks that the data for a joint are valid. + * @function ScriptAvatar.isJointDataValid + * @param {number} index - The index of the joint. + * @returns {boolean} true if the joint data are valid, false if not or the avatar data aren't + * available. + */ Q_INVOKABLE bool isJointDataValid(const QString& name) const; + + /**jsdoc + * Gets the joint index for a named joint. The joint index value is the position of the joint in the array returned by + * {@linkScriptAvatar.getJointNames}. + * @function ScriptAvatar.getJointIndex + * @param {string} name - The name of the joint. + * @returns {number} The index of the joint if valid and avatar data are available, otherwise -1. + */ Q_INVOKABLE int getJointIndex(const QString& name) const; + + /**jsdoc + * Gets the names of all the joints in the avatar. + * @function ScriptAvatar.getJointNames + * @returns {string[]} The joint names, or [] if the avatar data aren't available. + */ Q_INVOKABLE QStringList getJointNames() const; + + /**jsdoc + * Gets information about the models currently attached to the avatar. + * @function ScriptAvatar.getAttachmentData + * @returns {AttachmentData[]} Information about all models attached to the avatar, or [] if the avatar data + * aren't available. + * @deprecated This function is deprecated and will be removed. Use avatar entities instead. + */ Q_INVOKABLE QVector getAttachmentData() const; #if DEV_BUILD || PR_BUILD @@ -185,13 +232,54 @@ public: bool getHasPriority() const; signals: + + /**jsdoc + * Triggered when the avatar's displayName property value changes. + * @function ScriptAvatar.displayNameChanged + * @returns {Signal} + */ void displayNameChanged(); + + /**jsdoc + * Triggered when the avatar's sessionDisplayName property value changes. + * @function ScriptAvatar.sessionDisplayNameChanged + * @returns {Signal} + */ void sessionDisplayNameChanged(); + + /**jsdoc + * Triggered when the avatar's model (i.e., skeletonModelURL property value) is changed. + * @function ScriptAvatar.skeletonModelURLChanged + * @returns {Signal} + */ void skeletonModelURLChanged(); + + /**jsdoc + * Triggered when the avatar's lookAtSnappingEnabled property value changes. + * @function ScriptAvatar.lookAtSnappingChanged + * @param {boolean} enabled - true if look-at snapping is enabled, false if not. + * @returns {Signal} + */ void lookAtSnappingChanged(bool enabled); public slots: + + /**jsdoc + * Gets the rotation of a joint relative to the avatar. + * @function ScriptAvatar.getAbsoluteJointRotationInObjectFrame + * @param {number} index - The index of the joint. + * @returns {Quat} The rotation of the joint relative to the avatar, or {@link Quat(0)|Quat.IDENTITY} if the avatar data + * aren't available. + */ glm::quat getAbsoluteJointRotationInObjectFrame(int index) const; + + /**jsdoc + * Gets the translation of a joint relative to the avatar. + * @function ScriptAvatar.getAbsoluteJointTranslationInObjectFrame + * @param {number} index - The index of the joint. + * @returns {Vec3} The translation of the joint relative to the avatar, or {@link Vec3(0)|Vec3.ZERO} if the avatar data + * aren't available. + */ glm::vec3 getAbsoluteJointTranslationInObjectFrame(int index) const; protected: diff --git a/libraries/controllers/src/controllers/ScriptingInterface.h b/libraries/controllers/src/controllers/ScriptingInterface.h index 05e246deaa..a1875c7fe8 100644 --- a/libraries/controllers/src/controllers/ScriptingInterface.h +++ b/libraries/controllers/src/controllers/ScriptingInterface.h @@ -282,7 +282,7 @@ namespace controller { * Enables or disables a controller mapping. When enabled, the routes in the mapping have effect. * @function Controller.enableMapping * @param {string} mappingName - The name of the mapping. - * @param {boolean} [[enable=true] - If true then the mapping is enabled, otherwise it is disabled. + * @param {boolean} [enable=true] - If true then the mapping is enabled, otherwise it is disabled. */ Q_INVOKABLE void enableMapping(const QString& mappingName, bool enable = true); diff --git a/libraries/input-plugins/src/input-plugins/KeyboardMouseDevice.cpp b/libraries/input-plugins/src/input-plugins/KeyboardMouseDevice.cpp index b1b8875804..c436a5b510 100755 --- a/libraries/input-plugins/src/input-plugins/KeyboardMouseDevice.cpp +++ b/libraries/input-plugins/src/input-plugins/KeyboardMouseDevice.cpp @@ -356,17 +356,17 @@ controller::Input KeyboardMouseDevice::InputDevice::makeInput(KeyboardMouseDevic * new x-coordinate value. * MouseYnumbernumberThe mouse y-coordinate changed. The data value is its * new y-coordinate value. - * MouseWheelRightnumbernumberThe mouse wheel rotated right. The data value - * is the number of units rotated (typically 1.0). - * MouseWheelLeftnumbernumberThe mouse wheel rotated left. The data value - * is the number of units rotated (typically 1.0). - * MouseWheelUpnumbernumberThe mouse wheel rotated up. The data value - * is the number of units rotated (typically 1.0). + * MouseWheelRightnumbernumberThe mouse wheel rotated right or two-finger + * swipe moved right. The data value is the number of units moved (typically 1.0). + * MouseWheelLeftnumbernumberThe mouse wheel rotated left or two-finger + * swipe moved left. The data value is the number of units moved (typically 1.0). + * MouseWheelUpnumbernumberThe mouse wheel rotated up or two-finger swipe + * moved up. The data value is the number of units move3d (typically 1.0). *

Warning: The mouse wheel in an ordinary mouse generates left/right wheel events instead of * up/down.

* - * MouseWheelDownnumbernumberThe mouse wheel rotated down. The data value - * is the number of units rotated (typically 1.0). + * MouseWheelDownnumbernumberThe mouse wheel rotated down or two-finger + * swipe moved down. The data value is the number of units moved (typically 1.0). *

Warning: The mouse wheel in an ordinary mouse generates left/right wheel events instead of * up/down.

* @@ -378,7 +378,11 @@ controller::Input KeyboardMouseDevice::InputDevice::makeInput(KeyboardMouseDevic * moved up. The data value is how far the average position of all touch points moved. * TouchpadDownnumbernumberThe average touch on a touch-enabled device * moved down. The data value is how far the average position of all touch points moved. - * + * GesturePinchOutnumbernumberThe average of two touches on a touch-enabled + * device moved out. The data value is how far the average positions of the touch points moved out. + * GesturePinchOutnumbernumberThe average of two touches on a touch-enabled + * device moved in. The data value is how far the average positions of the touch points moved in. + * * * @typedef {object} Controller.Hardware-Keyboard */ diff --git a/libraries/procedural/src/procedural/Procedural.h b/libraries/procedural/src/procedural/Procedural.h index 89f21218e6..9b3d0a9bd4 100644 --- a/libraries/procedural/src/procedural/Procedural.h +++ b/libraries/procedural/src/procedural/Procedural.h @@ -27,7 +27,6 @@ using UniformLambdas = std::list>; const size_t MAX_PROCEDURAL_TEXTURE_CHANNELS{ 4 }; /**jsdoc - * An object containing user-defined uniforms for communicating data to shaders. * @typedef {object} ProceduralUniforms */ diff --git a/libraries/script-engine/src/ScriptEngine.cpp b/libraries/script-engine/src/ScriptEngine.cpp index 7e3f556c2d..9141b5e1c7 100644 --- a/libraries/script-engine/src/ScriptEngine.cpp +++ b/libraries/script-engine/src/ScriptEngine.cpp @@ -1009,6 +1009,12 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString& }); // Two common cases of event handler, differing only in argument signature. + + /**jsdoc + * Called when an entity event occurs on an entity as registered with {@link Script.addEventHandler}. + * @callback Script~entityEventCallback + * @param {Uuid} entityID - The ID of the entity the event has occured on. + */ using SingleEntityHandler = std::function; auto makeSingleEntityHandler = [this](QString eventName) -> SingleEntityHandler { return [this, eventName](const EntityItemID& entityItemID) { @@ -1016,6 +1022,12 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString& }; }; + /**jsdoc + * Called when a pointer event occurs on an entity as registered with {@link Script.addEventHandler}. + * @callback Script~pointerEventCallback + * @param {Uuid} entityID - The ID of the entity the event has occurred on. + * @param {PointerEvent} pointerEvent - Details of the event. + */ using PointerHandler = std::function; auto makePointerHandler = [this](QString eventName) -> PointerHandler { return [this, eventName](const EntityItemID& entityItemID, const PointerEvent& event) { @@ -1025,6 +1037,13 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString& }; }; + /**jsdoc + * Called when a collision event occurs on an entity as registered with {@link Script.addEventHandler}. + * @callback Script~collisionEventCallback + * @param {Uuid} entityA - The ID of one entity in the collision. + * @param {Uuid} entityB - The ID of the other entity in the collision. + * @param {Collision} collisionEvent - Details of the collision. + */ using CollisionHandler = std::function; auto makeCollisionHandler = [this](QString eventName) -> CollisionHandler { return [this, eventName](const EntityItemID& idA, const EntityItemID& idB, const Collision& collision) { @@ -1034,28 +1053,39 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString& }; /**jsdoc - *

The name of an entity event. When the entity event occurs, any function that has been registered for that event via - * {@link Script.addEventHandler} is called with parameters per the entity event.

+ *

The name of an entity event. When the entity event occurs, any function that has been registered for that event + * via {@link Script.addEventHandler} is called with parameters per the entity event.

* * - * + * * * - * - * - * - * - * - * - * - * - * - * - * - * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * * *
Event NameEntity Event
Event NameCallback TypeEntity Event
"enterEntity"{@link Entities.enterEntity}
"leaveEntity"{@link Entities.leaveEntity}
"mousePressOnEntity"{@link Entities.mousePressOnEntity}
"mouseMoveOnEntity"{@link Entities.mouseMoveOnEntity}
"mouseReleaseOnEntity"{@link Entities.mouseReleaseOnEntity}
"clickDownOnEntity"{@link Entities.clickDownOnEntity}
"holdingClickOnEntity"{@link Entities.holdingClickOnEntity}
"clickReleaseOnEntity"{@link Entities.clickReleaseOnEntity}
"hoverEnterEntity"{@link Entities.hoverEnterEntity}
"hoverOverEntity"{@link Entities.hoverOverEntity}
"hoverLeaveEntity"{@link Entities.hoverLeaveEntity}
"collisionWithEntity"{@link Entities.collisionWithEntity}
"enterEntity"{@link Script~entityEventCallback|entityEventCallback}{@link Entities.enterEntity}
"leaveEntity"{@link Script~entityEventCallback|entityEventCallback}{@link Entities.leaveEntity}
"mousePressOnEntity"{@link Script~pointerEventCallback|pointerEventCallback}{@link Entities.mousePressOnEntity}
"mouseMoveOnEntity"{@link Script~pointerEventCallback|pointerEventCallback}{@link Entities.mouseMoveOnEntity}
"mouseReleaseOnEntity"{@link Script~pointerEventCallback|pointerEventCallback}{@link Entities.mouseReleaseOnEntity}
"clickDownOnEntity"{@link Script~pointerEventCallback|pointerEventCallback}{@link Entities.clickDownOnEntity}
"holdingClickOnEntity"{@link Script~pointerEventCallback|pointerEventCallback}{@link Entities.holdingClickOnEntity}
"clickReleaseOnEntity"{@link Script~pointerEventCallback|pointerEventCallback}{@link Entities.clickReleaseOnEntity}
"hoverEnterEntity"{@link Script~pointerEventCallback|pointerEventCallback}{@link Entities.hoverEnterEntity}
"hoverOverEntity"{@link Script~pointerEventCallback|pointerEventCallback}{@link Entities.hoverOverEntity}
"hoverLeaveEntity"{@link Script~pointerEventCallback|pointerEventCallback}{@link Entities.hoverLeaveEntity}
"collisionWithEntity"{@link Script~collisionEventCallback|collisionEventCallback}{@link Entities.collisionWithEntity}
- * * @typedef {string} Script.EntityEvent */ connect(entities.data(), &EntityScriptingInterface::enterEntity, this, makeSingleEntityHandler("enterEntity")); diff --git a/libraries/script-engine/src/ScriptEngine.h b/libraries/script-engine/src/ScriptEngine.h index 3891f60d92..71af673e6c 100644 --- a/libraries/script-engine/src/ScriptEngine.h +++ b/libraries/script-engine/src/ScriptEngine.h @@ -320,13 +320,13 @@ public: // NOTE - these are intended to be public interfaces available to scripts /**jsdoc - * Adds a function to the list of functions called when an entity event occurs on a particular entity. + * Adds a function to the list of functions called when a particular event occurs on a particular entity. *

See also, the {@link Entities} API.

* @function Script.addEventHandler * @param {Uuid} entityID - The ID of the entity. - * @param {Script.EntityEvent} eventName - The name of the entity event. - * @param {function} handler - The function to call when the entity event occurs on the entity. It can be either the name - * of a function or an in-line definition. + * @param {Script.EntityEvent} eventName - The name of the event. + * @param {Script~entityEventCallback|Script~pointerEventCallback|Script~collisionEventCallback} handler - The function to + * call when the event occurs on the entity. It can be either the name of a function or an in-line definition. * @example Report when a mouse press occurs on a particular entity. * var entityID = Entities.addEntity({ * type: "Box", diff --git a/libraries/shared/src/JointData.h b/libraries/shared/src/JointData.h index 7a2420262a..3f957fa046 100644 --- a/libraries/shared/src/JointData.h +++ b/libraries/shared/src/JointData.h @@ -16,6 +16,7 @@ public: // Used by the avatar mixer to describe a single joint // Translations relative to their parent joint // Rotations are absolute (i.e. not relative to parent) and are in rig space. +// No JSDoc because its not provided as a type to the script engine. class JointData { public: glm::quat rotation; diff --git a/libraries/ui/src/QmlWebWindowClass.h b/libraries/ui/src/QmlWebWindowClass.h index 2c1a5eabbb..feca148614 100644 --- a/libraries/ui/src/QmlWebWindowClass.h +++ b/libraries/ui/src/QmlWebWindowClass.h @@ -108,7 +108,7 @@ * }, 2000); * * @example - * // HTML file, "OverlayWebWindow.qml". + * // HTML file, "OverlayWebWindow.html". * * * diff --git a/libraries/ui/src/ui/TabletScriptingInterface.h b/libraries/ui/src/ui/TabletScriptingInterface.h index c063307597..90b734b42d 100644 --- a/libraries/ui/src/ui/TabletScriptingInterface.h +++ b/libraries/ui/src/ui/TabletScriptingInterface.h @@ -423,6 +423,12 @@ public: * 
EventBridge.scriptEventReceived.connect(function(message) {
      *     ...
      * });
+ *

Warning: The EventBridge object is not necessarily set up immediately ready for the web + * page's script to use. A simple workaround that normally works is to add a delay before calling + * EventBridge.scriptEventReceived.connect(...). A better solution is to periodically call + * EventBridge.scriptEventReceived.connect(...) and then EventBridge.emitWebEvent(...) to send a + * message to the Interface script, and have that send a message back using emitScriptEvent(...); when the + * return message is received, the EventBridge is ready for use.

* @function TabletProxy#emitScriptEvent * @param {string|object} message - The message to send to the web page. */