CameraFirstPersonCameraFirstPersonLookAtCameraThirdPersonCameraFSMCameraLookAtCameraFSMCameraSelfieCameraIndependentCameraEntityInHMDDeprecated: 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.
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:
* 012Note: 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.
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 {Objecttrue 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
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
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.
| Value | Name | Description |
|---|---|---|
0 | TOP | Dock to the top edge of the Interface window. |
1 | BOTTOM | Dock to the bottom edge of the Interface window. |
2 | LEFT | Dock to the left edge of the Interface window. |
3 | RIGHT | Dock to the right edge of the Interface window. |
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.
| Value | Name | Description |
|---|---|---|
0 | VIRTUAL | The window is displayed inside Interface: in the desktop window in - * desktop mode or on the HUD surface in HMD mode. |
1 | NATIVE | The window is displayed separately from the Interface window, as its - * own separate window. |
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 true if the Interface window is minimized, false if it isn't.
* @returns {Signal}
+ * @example 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..
| Value | Name | Description | |
|---|---|---|---|
0x00000001 | Window | Displays the window as a window rather than a dialog. | |
0x00001000 | WindowTitleHint | Adds a title bar. | + * |
0x00002000 | WindowSystemMenuHint | Adds a window system menu. | + * |
0x00004000 | WindowMinimizeButtonHint | Adds a minimize button. | + * |
0x00008000 | WindowMaximizeButtonHint | Adds a maximize button. | + * |
0x00040000 | WindowStaysOnTopHint | The window stays on top of other windows. + * Not used on Windows. + * | |
0x08000000 | WindowCloseButtonHint | Adds a close button. | + * |
A display mode for an InteractiveWindow.
| Value | Name | Description |
|---|---|---|
0 | VIRTUAL | The window is displayed inside Interface: in the desktop window in + * desktop mode or on the HUD surface in HMD mode. |
1 | NATIVE | The window is displayed separately from the Interface window, as its + * own separate window. |
A docking location of an InteractiveWindow.
| Value | Name | Description |
|---|---|---|
0 | TOP | Dock to the top edge of the Interface window. |
1 | BOTTOM | Dock to the bottom edge of the Interface window. |
2 | LEFT | Dock to the left edge of the Interface window. |
3 | RIGHT | Dock to the right edge of the Interface window. |
The anchor for a relative position of an InteractiveWindow.
| Value | Name | Description |
|---|---|---|
0 | NO_ANCHOR | Position is not relative to any part of the Interface window. |
1 | TOP_LEFT | Position is offset from the top left of the Interface window. |
2 | TOP_RIGHT | Position is offset from the top right of the Interface window. |
3 | BOTTOM_RIGHT | Position offset from the bottom right of the Interface + * window. |
4 | BOTTOM_LEFFT | Position is offset from the bottom left of the Interface + * window. |
Create using {@link Desktop.createWindow}.
* * @class InteractiveWindow + * @hideconstructor * * @hifi-interface * @hifi-client-entity * @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/animation/src/AnimationObject.h b/libraries/animation/src/AnimationObject.h
index 303d0e0d9e..40fd534a71 100644
--- a/libraries/animation/src/AnimationObject.h
+++ b/libraries/animation/src/AnimationObject.h
@@ -23,6 +23,7 @@ class QScriptEngine;
* Information about an animation resource, created by {@link AnimationCache.getAnimation}.
*
* @class AnimationObject
+ * @hideconstructor
*
* @hifi-interface
* @hifi-client-entity
@@ -57,9 +58,10 @@ public:
};
/**jsdoc
- * Joint rotations in one frame of an animation.
+ * Joint rotations in one frame of an {@link AnimationObject}.
*
* @class AnimationFrameObject
+ * @hideconstructor
*
* @hifi-interface
* @hifi-client-entity
diff --git a/libraries/audio-client/src/AudioIOStats.h b/libraries/audio-client/src/AudioIOStats.h
index 26ea301eaa..9265ae3062 100644
--- a/libraries/audio-client/src/AudioIOStats.h
+++ b/libraries/audio-client/src/AudioIOStats.h
@@ -42,9 +42,10 @@ class AudioStreamStatsInterface : public QObject {
/**jsdoc
* Statistics for an audio stream.
*
- * Provided in the {@link AudioStats} API.
+ *Provided in properties of the {@link AudioStats} API.
* * @class AudioStats.AudioStreamStats + * @hideconstructor * * @hifi-interface * @hifi-client-entity diff --git a/libraries/audio/src/AudioEffectOptions.h b/libraries/audio/src/AudioEffectOptions.h index e090832510..48fe44feb5 100644 --- a/libraries/audio/src/AudioEffectOptions.h +++ b/libraries/audio/src/AudioEffectOptions.h @@ -18,7 +18,7 @@ /**jsdoc * Audio effect options used by the {@link Audio} API. * - *Create using new AudioEffectOptions(reverbOptions).
Create using new AudioEffectOptions(...).
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 QListCreated 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.
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} totrue. 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.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.
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 QVectorWarning: 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 QVectortrue 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 QVectordisplayName 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/controllers/src/controllers/impl/MappingBuilderProxy.h b/libraries/controllers/src/controllers/impl/MappingBuilderProxy.h
index 5a8fd3083d..9dafc03f1f 100644
--- a/libraries/controllers/src/controllers/impl/MappingBuilderProxy.h
+++ b/libraries/controllers/src/controllers/impl/MappingBuilderProxy.h
@@ -54,6 +54,7 @@ class UserInputMapper;
*
*
* @class MappingObject
+ * @hideconstructor
*
* @hifi-interface
* @hifi-client-entity
diff --git a/libraries/controllers/src/controllers/impl/RouteBuilderProxy.h b/libraries/controllers/src/controllers/impl/RouteBuilderProxy.h
index f1b36cfec5..38b18346a8 100644
--- a/libraries/controllers/src/controllers/impl/RouteBuilderProxy.h
+++ b/libraries/controllers/src/controllers/impl/RouteBuilderProxy.h
@@ -36,6 +36,7 @@ class ScriptingInterface;
* types.
*
* @class RouteObject
+ * @hideconstructor
*
* @hifi-interface
* @hifi-client-entity
diff --git a/libraries/entities/src/EntityScriptingInterface.h b/libraries/entities/src/EntityScriptingInterface.h
index fb1ec56503..d1e83dccc2 100644
--- a/libraries/entities/src/EntityScriptingInterface.h
+++ b/libraries/entities/src/EntityScriptingInterface.h
@@ -1867,7 +1867,8 @@ public slots:
* @function Entities.getMeshes
* @param {Uuid} entityID - The ID of the Currently not used. Currently not used. Currently not used. Note: The model data may be used for more than one instance of the item displayed in the scene. Created using the {@link Graphics} API, {@link GraphicsModel.cloneModel}, or {@link GraphicsMesh.cloneMesh}. Currently doesn't work. Note: The Created using the {@link Graphics} API, {@link GraphicsModel.cloneModel}, {@link GraphicsMesh.cloneMesh}, or
+ * {@link GraphicsMeshPart.cloneMeshPart}. Warning: Currently doesn't work as expected. Warning: Currently doesn't work as expected. Note: The Note: The model may be used for more than one instance of an item displayed in the scene. Modifying the model updates
+ * all instances displayed. Created using the {@link Graphics} API or {@link GraphicsModel.cloneModel}. The type name of a graphics buffer. The type of a graphics buffer value as accessed by JavaScript. The interpretation of mesh elements.Model or PolyVox entity to get the meshes of.
* @param {Entities~getMeshesCallback} callback - The function to call upon completion.
- * @deprecated This function is deprecated and will be removed. Use the {@link Graphics} API instead.
+ * @deprecated This function is deprecated and will be removed. It no longer works for Model entities. Use the
+ * {@link Graphics} API instead.
*/
/**jsdoc
* Called when a {@link Entities.getMeshes} call is complete.
@@ -1876,7 +1877,8 @@ public slots:
* Model or PolyVox entity; otherwise undefined.
* @param {boolean} success - true if the {@link Entities.getMeshes} call was successful, false
* otherwise. The call may be unsuccessful if the requested entity could not be found.
- * @deprecated This function is deprecated and will be removed. Use the {@link Graphics} API instead.
+ * @deprecated This function is deprecated and will be removed. It no longer works for Model entities. Use the
+ * {@link Graphics} API instead.
*/
// FIXME move to a renderable entity interface
Q_INVOKABLE void getMeshes(const QUuid& entityID, QScriptValue callback);
diff --git a/libraries/graphics-scripting/src/graphics-scripting/Forward.h b/libraries/graphics-scripting/src/graphics-scripting/Forward.h
index acef5a5bd4..29f8079422 100644
--- a/libraries/graphics-scripting/src/graphics-scripting/Forward.h
+++ b/libraries/graphics-scripting/src/graphics-scripting/Forward.h
@@ -36,39 +36,6 @@ namespace scriptable {
using ModelProviderPointer = std::shared_ptrtopology.
+ * @property {Vec3[]} positions - Vertex positions, in model coordinates.
+ * @property {Vec3[]} [normals=[]] - Vertex normals (normalized).
+ * @property {Vec3[]} [colors=[]] - Vertex colors (normalized).
+ * @property {Vec2[]} [texCoords0=[]] - Vertex texture coordinates (normalized).
*/
QString meshName = ifsMeshData.value("name").toString();
QString topologyName = ifsMeshData.value("topology").toString();
@@ -354,6 +355,120 @@ namespace scriptable {
qScriptValueToSequence(array, result);
}
+ /**jsdoc
+ * A material in a {@link GraphicsModel}.
+ * @typedef {object} Graphics.Material
+ * @property {string} name - The name of the material.
+ * @property {string} model - Different material models support different properties and rendering modes. Supported models
+ * are: "hifi_pbr" and "hifi_shader_simple".
+ * @property {Vec3|string} [albedo] - The albedo color. Component values are in the range 0.0 –
+ * 1.0.
+ * If "fallthrough" then it falls through to the material below.
+ * @property {number|string} [opacity] - The opacity, range 0.0 – 1.0.
+ * If "fallthrough" then it falls through to the material below.
+ *
+ * @property {number|string} [opacityCutoff] - The opacity cutoff threshold used to determine the opaque texels of the
+ * opacityMap when opacityMapMode is "OPACITY_MAP_MASK". Range 0.0
+ * – 1.0.
+ * If "fallthrough" then it falls through to the material below.
+ * "hifi_pbr" model only.
+ * @property {number|string} [roughness] - The roughness, range 0.0 – 1.0.
+ * If "fallthrough" then it falls through to the material below.
+ * "hifi_pbr" model only.
+ * @property {number|string} [metallic] - The metallicness, range 0.0 – 1.0.
+ * If "fallthrough" then it falls through to the material below.
+ * "hifi_pbr" model only.
+ * @property {number|string} [scattering] - The scattering, range 0.0 – 1.0.
+ * If "fallthrough" then it falls through to the material below.
+ * "hifi_pbr" model only.
+ * @property {boolean|string} [unlit] - true if the material is unaffected by lighting, false if it
+ * it is lit by the key light and local lights.
+ * If "fallthrough" then it falls through to the material below.
+ * "hifi_pbr" model only.
+ * @property {Vec3|string} [emissive] - The emissive color, i.e., the color that the material emits. Component values are
+ * in the range 0.0 – 1.0.
+ * If "fallthrough" then it falls through to the material below.
+ * "hifi_pbr" model only.
+ * @property {string} [albedoMap] - The URL of the albedo texture image.
+ * If "fallthrough" then it falls through to the material below.
+ * "hifi_pbr" model only.
+ * @property {string} [opacityMap] - The URL of the opacity texture image.
+ * "hifi_pbr" model only.
+ * @property {string} [opacityMapMode] - The mode defining the interpretation of the opacity map. Values can be:
+ *
+ *
+ * If "OPACITY_MAP_OPAQUE" for ignoring the opacity map information."OPACITY_MAP_MASK" for using the opacityMap as a mask, where only the texel greater
+ * than opacityCutoff are visible and rendered opaque."OPACITY_MAP_BLEND" for using the opacityMap for alpha blending the material surface
+ * with the background."fallthrough" then it falls through to the material below.
+ * "hifi_pbr" model only.
+ * @property {string} [occlusionMap] - The URL of the occlusion texture image.
+ * If "fallthrough" then it falls through to the material below.
+ * "hifi_pbr" model only.
+ * @property {string} [lightMap] - The URL of the light map texture image.
+ * If "fallthrough" then it falls through to the material below.
+ * "hifi_pbr" model only.
+ * @property {string} [lightmapParams] - Parameters for controlling how lightMap is used.
+ * If "fallthrough" then it falls through to the material below.
+ * "hifi_pbr" model only.
+ * "fallthrough" then it falls through to the material below.
+ * "hifi_pbr" model only.
+ * @property {string} [emissiveMap] - The URL of the emissive texture image.
+ * If "fallthrough" then it falls through to the material below.
+ * "hifi_pbr" model only.
+ * @property {string} [metallicMap] - The URL of the metallic texture image.
+ * If "fallthrough" then it and specularMap fall through to the material below.
+ * Only use one of metallicMap and specularMap.
+ * "hifi_pbr" model only.
+ * @property {string} [specularMap] - The URL of the specular texture image.
+ * Only use one of metallicMap and specularMap.
+ * "hifi_pbr" model only.
+ * @property {string} [roughnessMap] - The URL of the roughness texture image.
+ * If "fallthrough" then it and glossMap fall through to the material below.
+ * Only use one of roughnessMap and glossMap.
+ * "hifi_pbr" model only.
+ * @property {string} [glossMap] - The URL of the gloss texture image.
+ * Only use one of roughnessMap and glossMap.
+ * "hifi_pbr" model only.
+ * @property {string} [normalMa]p - The URL of the normal texture image.
+ * If "fallthrough" then it and bumpMap fall through to the material below.
+ * Only use one of normalMap and bumpMap.
+ * "hifi_pbr" model only.
+ * @property {string} [bumpMap] - The URL of the bump texture image.
+ * Only use one of normalMap and bumpMap.
+ * "hifi_pbr" model only.
+ * @property {string} [materialParams] - Parameters for controlling the material projection and repetition.
+ * If "fallthrough" then it falls through to the material below.
+ * "hifi_pbr" model only.
+ *
+ *
+ * If "CULL_NONE" to render both sides of the geometry."CULL_FRONT" to cull the front faces of the geometry."CULL_BACK" (the default) to cull the back faces of the geometry."fallthrough" then it falls through to the material below.
+ * "hifi_pbr" model only.
+ * @property {Mat4|string} [texCoordTransform0] - The transform to use for all of the maps apart from
+ * occlusionMap and lightMap.
+ * If "fallthrough" then it falls through to the material below.
+ * "hifi_pbr" model only.
+ * @property {Mat4|string} [texCoordTransform1] - The transform to use for occlusionMap and
+ * lightMap.
+ * If "fallthrough" then it falls through to the material below.
+ * "hifi_pbr" model only.
+ *
+ * @property {string} procedural - The definition of a procedural shader material.
+ * "hifi_shader_simple" model only.
+ * true if all properties fall through to the material below unless
+ * they are set, false if properties respect their individual fall-through settings.
+ */
QScriptValue scriptableMaterialToScriptValue(QScriptEngine* engine, const scriptable::ScriptableMaterial &material) {
QScriptValue obj = engine->newObject();
obj.setProperty("name", material.name);
diff --git a/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingInterface.h b/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingInterface.h
index c1f3be2b3d..9b56433bf6 100644
--- a/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingInterface.h
+++ b/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingInterface.h
@@ -23,7 +23,10 @@
/**jsdoc
- * The experimental Graphics API (experimental) lets you query and manage certain graphics-related structures (like underlying meshes and textures) from scripting.
+ * The Graphics API enables you to access and manipulate avatar, entity, and overlay models in the rendered scene.
+ * This includes getting mesh and material information for applying {@link Entities.EntityProperties-Material|Material}
+ * entities.
+ *
* @namespace Graphics
*
* @hifi-interface
@@ -40,44 +43,83 @@ public:
public slots:
/**jsdoc
- * Returns a model reference object associated with the specified UUID ({@link EntityID} or {@link AvatarID}).
- *
+ * Gets a handle to the model data used for displaying an avatar, 3D entity, or 3D overlay.
+ * true if the update was completed successfully, false if it wasn't.
*/
bool updateModel(const QUuid& uuid, const scriptable::ScriptableModelPointer& model);
/**jsdoc
+ * Checks whether the model for an avatar, entity, or overlay can be updated in the rendered scene. Only avatars,
+ * "Model" entities and "model" overlays can have their meshes updated.
* @function Graphics.canUpdateModel
- * @param {Uuid} id
- * @param {number} [meshIndex=-1]
- * @param {number} [partNumber=-1]
- * @returns {boolean}
+ * @param {Uuid} id - The ID of the avatar, entity, or overlay.
+ * @param {number} [meshIndex=-1] - Not used.
+ * @param {number} [partNumber=-1] - Not used.
+ * @returns {boolean} true if the model can be updated, false if it can't.
+ * @example false to not update the particular vertex.
+ * @callback GraphicsMesh~updateVertexAttributesCallback
+ * @param {Objectfalse to not update the vertex.
+ */
glm::uint32 scriptable::ScriptableMesh::updateVertexAttributes(QScriptValue _callback) {
auto mesh = getMeshPointer();
if (!mesh) {
diff --git a/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.h b/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.h
index dcb1c53759..8d70eda9e4 100644
--- a/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.h
+++ b/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.h
@@ -29,17 +29,41 @@
namespace scriptable {
/**jsdoc
- * @typedef {object} Graphics.Mesh
- * @property {Graphics.MeshPart[]} parts - Array of submesh part references.
- * @property {string[]} attributeNames - Vertex attribute names (color, normal, etc.)
- * @property {number} numParts - The number of parts contained in the mesh.
- * @property {number} numIndices - Total number of vertex indices in the mesh.
- * @property {number} numVertices - Total number of vertices in the Mesh.
- * @property {number} numAttributes - Number of currently defined vertex attributes.
- * @property {boolean} valid
- * @property {boolean} strong
- * @property {object} extents
- * @property {object} bufferFormats
+ * A handle to in-memory mesh data in a {@link GraphicsModel}.
+ *
+ * true if the mesh is valid, false if it isn't.
+ * Read-only.
+ * @property {boolean} strong - true if the mesh is valid and able to be used, false if it isn't.
+ * Read-only.
+ * @property {Graphics.MeshExtents} extents - The mesh extents, in model coordinates.
+ * Read-only.
+ * @property {Objectnull if it isn't part of a model.
+ */
const scriptable::ScriptableModelPointer getParentModel() const { return qobject_castorigin it is considered to be "nearby".
+ * @returns {number[]} The indices of nearby vertices.
+ */
QVector0 if the name was
+ * invalid or all vertices already had the attribute.
+ */
glm::uint32 addAttribute(const QString& attributeName, const QVariant& defaultValue = QVariant());
+
+ /**jsdoc
+ * Sets the value of an attribute for all vertices.
+ * @function GraphicsMesh.fillAttribute
+ * @param {Graphics.BufferTypeName} name - The name of the attribute. The attribute is added to the vertices if not
+ * already present.
+ * @param {Graphics.BufferType} value - The value to give the attributes.
+ * @returns {number} 1 if the attribute name was valid and the attribute values were set, 0
+ * otherwise.
+ */
glm::uint32 fillAttribute(const QString& attributeName, const QVariant& value);
+
+ /**jsdoc
+ * Removes an attribute from all vertices.
+ * "position" attribute cannot be removed.true if the attribute existed and was removed, false otherwise.
+ */
bool removeAttribute(const QString& attributeName);
+ /**jsdoc
+ * Gets the value of an attribute for all vertices.
+ * @function GraphicsMesh.queryVertexAttributes
+ * @param {Graphics.BufferTypeName} name - The name of the attribute to get the vertex values of.
+ * @throws Throws an error if the name is invalid or isn't used in the mesh.
+ * @returns {Graphics.BufferType[]} The attribute values for all vertices.
+ */
QVariantList queryVertexAttributes(QVariant selector) const;
+
+ /**jsdoc
+ * Gets the attributes and attribute values of a vertex.
+ * @function GraphicsMesh.getVertexAttributes
+ * @param {number} index - The vertex to get the attributes for.
+ * @returns {Objectindex is invalid.
+ */
QVariantMap getVertexAttributes(glm::uint32 vertexIndex) const;
+
+ /**jsdoc
+ * Updates attribute values of a vertex.
+ * @function GraphicsMesh.setVertexAttributes
+ * @param {number} index - The vertex to set the attributes for.
+ * @param {Objecttrue if the index and the attribute names and values were valid and the vertex was
+ * updated, false otherwise.
+ * @throws Throws an error if the index is invalid or one of the attribute names is invalid or isn't used
+ * in the mesh.
+ */
+ // @borrows jsdoc from GraphicsMesh
bool setVertexAttributes(glm::uint32 vertexIndex, const QVariantMap& attributeValues);
+ /**jsdoc
+ * Gets the value of a vertex's attribute.
+ * @function GraphicsMesh.getVertexProperty
+ * @param {number} index - The vertex index.
+ * @param {Graphics.BufferTypeName} name - The name of the vertex attribute to get.
+ * @returns {Graphics.BufferType} The value of the vertex attribute.
+ * @throws Throws an error if the index is invalid or name is invalid or isn't used in the
+ * mesh.
+ */
QVariant getVertexProperty(glm::uint32 vertexIndex, const QString& attributeName) const;
+
+ /**jsdoc
+ * Sets the value of a vertex's attribute.
+ * @function GraphicsMesh.setVertexProperty
+ * @param {number} index - The vertex index.
+ * @param {Graphics.BufferTypeName} name - The name of the vertex attribute to set.
+ * @param {Graphics.BufferType} value - The vertex attribute value to set.
+ * @returns {boolean} true if the vertex attribute value was set, false if it wasn't.
+ * @throws Throws an error if the index is invalid or name is invalid or isn't used in the
+ * mesh.
+ */
bool setVertexProperty(glm::uint32 vertexIndex, const QString& attributeName, const QVariant& value);
+ /**jsdoc
+ * Makes a copy of the mesh.
+ * @function GraphicsMesh.cloneMesh
+ * @returns {GraphicsMesh} A copy of the mesh.
+ */
scriptable::ScriptableMeshPointer cloneMesh();
// QScriptEngine-specific wrappers
+
+ /**jsdoc
+ * Updates vertex attributes by calling a function for each vertex. The function can return modified attributes to
+ * update the vertex with.
+ * @function GraphicsMesh.updateVertexAttributes
+ * @param {GraphicsMesh~updateVertexAttributesCallback} callback - The function to call for each vertex.
+ * @returns {number} The number of vertices the callback was called for.
+ */
glm::uint32 updateVertexAttributes(QScriptValue callback);
+
+ /**jsdoc
+ * Calls a function for each vertex.
+ * @function GraphicsMesh.forEachVertex
+ * @param {GraphicsMesh~forEachVertexCallback} callback - The function to call for each vertex.
+ * @returns {number} The number of vertices the callback was called for.
+ */
glm::uint32 forEachVertex(QScriptValue callback);
+
+ /**jsdoc
+ * Checks if an index is valid and, optionally, that vertex has a particular attribute.
+ * @function GraphicsMesh.isValidIndex
+ * @param {number} index - The index to check.
+ * @param {Graphics.BufferTypeName} [attribute] - The attribute to check.
+ * @returns {boolean} true if the index is valid and that vertex has the attribute if specified.
+ * @throws Throws an error if the index if invalid or name is invalid or isn't used in the
+ * mesh.
+ */
+ // FIXME: Should return false rather than throw an error.
bool isValidIndex(glm::uint32 vertexIndex, const QString& attributeName = QString()) const;
};
diff --git a/libraries/graphics-scripting/src/graphics-scripting/ScriptableMeshPart.h b/libraries/graphics-scripting/src/graphics-scripting/ScriptableMeshPart.h
index 7352fcd0f6..78ddb4f2b0 100644
--- a/libraries/graphics-scripting/src/graphics-scripting/ScriptableMeshPart.h
+++ b/libraries/graphics-scripting/src/graphics-scripting/ScriptableMeshPart.h
@@ -11,23 +11,50 @@
namespace scriptable {
/**jsdoc
- * @typedef {object} Graphics.MeshPart
- * @property {boolean} valid
- * @property {number} partIndex - The part index (within the containing Mesh).
- * @property {number} firstVertexIndex
- * @property {number} baseVertexIndex
- * @property {number} lastVertexIndex
- * @property {Graphics.Topology} topology - element interpretation (currently only 'triangles' is supported).
- * @property {string[]} attributeNames - Vertex attribute names (color, normal, etc.)
- * @property {number} numIndices - Number of vertex indices that this mesh part refers to.
- * @property {number} numVerticesPerFace - Number of vertices per face (eg: 3 when topology is 'triangles').
- * @property {number} numFaces - Number of faces represented by the mesh part (numIndices / numVerticesPerFace).
- * @property {number} numVertices - Total number of vertices in the containing Mesh.
- * @property {number} numAttributes - Number of currently defined vertex attributes.
- * @property {object} extents
- * @property {object} bufferFormats
- */
+ * A handle to in-memory mesh part data in a {@link GraphicsModel}.
+ *
+ * true if the mesh part is valid, false if it isn't.
+ * Read-only.
+ * @property {number} partIndex - The index of the part within the whole mesh (i.e., parent and mesh parts).
+ * Read-only.
+ * @property {number} firstVertexIndex - The index of the first vertex.
+ * @property {number} baseVertexIndex - The index of the base vertex.
+ * @property {number} lastVertexIndex - The index of the last vertex.
+ * @property {Graphics.MeshTopology} topology - The element interpretation. Currently only triangles is supported.
+ * @property {number} numIndices - The number of vertex indices in the mesh part.
+ * @property {number} numVertices - The number of vertices in the whole mesh (i.e., parent and mesh parts).
+ * Read-only.
+ * @property {number} numVerticesPerFace - The number of vertices per face, per the topology (e.g., 3 for
+ * triangles).
+ * Read-only.
+ * @property {number} numFaces - The number of faces represented by the mesh part.
+ * Read-only.
+ * @property {number} numAttributes - The number of vertex attributes in the whole mesh (i.e., parent and mesh
+ * parts).
+ * Read-only.
+ * @property {Graphics.BufferTypeName[]} attributeNames - The names of the vertex attributes in the whole mesh
+ * (i.e., parent and mesh parts).
+ * Read-only.
+ * @property {Graphics.MeshExtents} extents - The mesh part extents, in model coordinates.
+ * Read-only.
+ * @property {Objecttrue if successful, false if not.
+ * @throws Throws an error if the number of indices isn't the same, or an index is invalid.
+ */
bool setIndices(const QVectororigin it is considered to be "nearby".
+ * @returns {number[]} The indices of nearby vertices.
+ */
QVectorname is invalid or isn't used in the mesh.
+ * @returns {Graphics.BufferType[]} The attribute values for all vertices.
+ */
QVariantList queryVertexAttributes(QVariant selector) const;
+
+ // @borrows jsdoc from GraphicsMesh.
QVariantMap getVertexAttributes(glm::uint32 vertexIndex) const;
+
+ // @borrows jsdoc from GraphicsMesh.
bool setVertexAttributes(glm::uint32 vertexIndex, const QVariantMap& attributeValues);
+ /**jsdoc
+ * Gets the value of a vertex's attribute.
+ * @function GraphicsMeshPart.getVertexProperty
+ * @param {number} index - The vertex index.
+ * @param {Graphics.BufferTypeName} name - The name of the vertex attribute to get.
+ * @returns {Graphics.BufferType} The value of the vertex attribute.
+ * @throws Throws an error if the index is invalid or name is invalid or isn't used in the
+ * mesh.
+ */
QVariant getVertexProperty(glm::uint32 vertexIndex, const QString& attributeName) const;
+
+ /**jsdoc
+ * Sets the value of a vertex's attribute.
+ * @function GraphicsMeshPart.setVertexProperty
+ * @param {number} index - The vertex index.
+ * @param {Graphics.BufferTypeName} name - The name of the vertex attribute to set.
+ * @param {Graphics.BufferType} value - The vertex attribute value to set.
+ * @returns {boolean} true if the vertex attribute value was set, false if it wasn't.
+ * @throws Throws an error if the index is invalid or name is invalid or isn't used in the
+ * mesh.
+ */
bool setVertexProperty(glm::uint32 vertexIndex, const QString& attributeName, const QVariant& attributeValues);
+ /**jsdoc
+ * Gets the vertex indices that make up a face.
+ * @function GraphicsMeshPart.getFace
+ * @param {number} index - The index of the face.
+ * @returns {number[]} The vertex indices that make up the face, of number per the mesh topology.
+ */
QVector1 if the attribute name was valid and the attribute values were set, 0
+ * otherwise.
+ */
glm::uint32 fillAttribute(const QString& attributeName, const QVariant& value);
+
+ /**jsdoc
+ * Removes an attribute from all vertices in the whole mesh (i.e., parent and mesh parts).
+ * "position" attribute cannot be removed.true if the attribute existed and was removed, false otherwise.
+ */
bool removeAttribute(const QString& attributeName);
+
+ /**jsdoc
+ * Deduplicates vertices.
+ * @function GraphicsMeshPart.dedupeVertices
+ * @param {number} [epsilon=1e-6] - The deduplicadtion distance. If a pair of vertices is within this distance of each
+ * other they are combined into a single vertex.
+ * @returns {boolean} true if the deduplication succeeded, false if it didn't.
+ */
bool dedupeVertices(float epsilon = 1e-6);
+ /**jsdoc
+ * Gets the parent mesh.
+ * @function GraphicsMeshPart.getParentMesh
+ * @returns {GraphicsMesh} The parent mesh.
+ */
scriptable::ScriptableMeshPointer getParentMesh() const { return parentMesh; }
+ /**jsdoc
+ * Replaces a mesh part with a copy of another mesh part.
+ * @function GraphicsMeshPart.replaceMeshPartData
+ * @param {GrphicsMeshPart} source - The mesh part to copy.
+ * @param {Graphics.BufferTypeName[]} [attributes] - The attributes to copy. If not specified, all attributes are
+ * copied from the source.
+ * @throws Throws an error if the mesh part of source mesh part aren't valid.
+ * @returns {boolean} true if the mesh part was successfully replaced, false if it wasn't.
+ */
bool replaceMeshPartData(scriptable::ScriptableMeshPartPointer source, const QVectortrue if the index is valid and that vertex has the attribute if specified.
+ * @throws Throws an error if the index if invalid or name is invalid or isn't used in the
+ * mesh.
+ */
+ // FIXME: Should return false rather than throw an error.
bool isValidIndex(glm::uint32 vertexIndex, const QString& attributeName = QString()) const;
+
public:
scriptable::ScriptableMeshPointer parentMesh;
glm::uint32 partIndex;
diff --git a/libraries/graphics-scripting/src/graphics-scripting/ScriptableModel.h b/libraries/graphics-scripting/src/graphics-scripting/ScriptableModel.h
index 7d1ca5f560..6dc2a06747 100644
--- a/libraries/graphics-scripting/src/graphics-scripting/ScriptableModel.h
+++ b/libraries/graphics-scripting/src/graphics-scripting/ScriptableModel.h
@@ -17,14 +17,36 @@ namespace scriptable {
using ScriptableMeshes = QVectornull
+ * if the model is not associated with an entity or avatar.
+ * Read-only.
+ * @property {number} numMeshes - The number of meshes contained in the model.
+ * Read-only.
+ * @property {GraphicsMesh[]} meshes - The meshes in the model. Each mesh may have more than one mesh part.
+ * Read-only.
+ * @property {string[]} materialNames - The names of the materials used by each mesh part in the model. The names are in
+ * the order of the meshes and their mesh parts.
+ * Read-only.
+ * @property {Object."0" per the array indexes of
+ * materialNames. The material names are those used in materialNames. (You can look up a
+ * material layer by mesh part number or by material name.)
+ * Read-only.
*/
-
class ScriptableModel : public ScriptableModelBase {
Q_OBJECT
Q_PROPERTY(QUuid objectID MEMBER objectID CONSTANT)
@@ -49,7 +71,23 @@ namespace scriptable {
QVector
+ *
+ *
+ * @typedef {string} Graphics.BufferTypeName
+ */
+/**jsdoc
+ * Value Description "position"Position buffer. "normal"normal buffer. "tangent"Tangent buffer. "color"Color buffer. "skin_cluster_index"Skin cluster index buffer. "skin_cluster_weight"Skin cluster weight buffer. "texcoord0"First UV coordinates buffer. "texcoord1"Second UV coordinates buffer. "texcoord2"Third UV coordinates buffer. "texcoord3"Fourth UV coordinates buffer. "texcoord4"Fifth UV coordinates buffer.
+ *
+ *
+ * @typedef {Vec3|vec2} Graphics.BufferType
+ */
QMapType Name Description {@link Vec3} "position"Position buffer. {@link Vec3} "normal"normal buffer. {@link Vec3} "tangent"Tangent buffer. {@link Vec4} "color"Color buffer. {@link Vec4} "skin_cluster_index"Skin cluster index buffer. {@link Vec4} "skin_cluster_weight"Skin cluster weight buffer. {@link Vec2} "texcoord0"First UV coordinates buffer. {@link Vec2} "texcoord1"Second UV coordinates buffer. {@link Vec2} "texcoord2"Third UV coordinates buffer. {@link Vec2} "texcoord3"Fourth UV coordinates buffer. {@link Vec2} "texcoord4"Fifth UV coordinates buffer.
- *
- *
- * @typedef {number} Graphics.Topology
- */
enum Topology {
POINTS = 0,
LINES,
diff --git a/libraries/graphics/src/graphics/GpuHelpers.cpp b/libraries/graphics/src/graphics/GpuHelpers.cpp
index b864b0f040..dd911e33c2 100644
--- a/libraries/graphics/src/graphics/GpuHelpers.cpp
+++ b/libraries/graphics/src/graphics/GpuHelpers.cpp
@@ -8,6 +8,24 @@
#include "GpuHelpers.h"
+/**jsdoc
+ * Value Description 0Points. 1Lines. 2Line strip. 3Triangles. 4Triangle strip. 5Quads. 6Quad strip.
+ *
+ *
+ * @typedef {string} Graphics.MeshTopology
+ */
namespace graphics {
DebugEnumsValue Description "points"Points. "lines"Lines. "line_strip"Line strip. "triangles"Triangles. "triangle_strip"Triangle strip. "quads"Quads. "quad_strip"Quad strip.
MouseYMouseWheelRight1.0).MouseWheelLeft1.0).MouseWheelUp1.0).
+ * MouseWheelRight1.0).MouseWheelLeft1.0).MouseWheelUp1.0).
* Warning: The mouse wheel in an ordinary mouse generates left/right wheel events instead of * up/down.
*MouseWheelDown1.0).
+ * MouseWheelDown1.0).
* Warning: The mouse wheel in an ordinary mouse generates left/right wheel events instead of * up/down.
*TouchpadDownGesturePinchOutGesturePinchOut"hifi_pbr" model only.
* @property {string} opacityMapMode - The mode defining the interpretation of the opacity map. Values can be:
* "OPACITY_MAP_OPAQUE" for ignoring the opacityMap information."OPACITY_MAP_OPAQUE" for ignoring the opacity map information."OPACITY_MAP_MASK" for using the opacityMap as a mask, where only the texel greater
* than opacityCutoff are visible and rendered opaque."OPACITY_MAP_BLEND" for using the opacityMap for alpha blending the material surface
@@ -153,14 +153,14 @@ NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMater
* "fallthrough" to fall through to the material below. "hifi_pbr" model only.
* @property {number|string} opacityCutoff - The opacity cutoff threshold used to determine the opaque texels of the
- * opacityMap when opacityMapMode is "OPACITY_MAP_MASK", range 0.0
+ * opacityMap when opacityMapMode is "OPACITY_MAP_MASK". Range 0.0
* – 1.0.
* Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only.
- * @property {string} cullFaceMode - The mode defining which side of the geometry should be rendered. Values can be:
+ * @property {string} cullFaceMode="CULL_BACK" - The mode defining which side of the geometry should be rendered. Values can be:
* "CULL_NONE" for rendering both sides of the geometry."CULL_FRONT" for culling the front faces of the geometry."CULL_BACK" (the default) for culling the back faces of the geometry."CULL_NONE" to render both sides of the geometry."CULL_FRONT" to cull the front faces of the geometry."CULL_BACK" (the default) to cull the back faces of the geometry."fallthrough" to fall through to the material below. "hifi_pbr" model only.
* @property {string} roughnessMap - The URL of the roughness texture image. You can use this or glossMap, but not
diff --git a/libraries/script-engine/src/AssetScriptingInterface.cpp b/libraries/script-engine/src/AssetScriptingInterface.cpp
index 33be9de2ad..f088ad7a38 100644
--- a/libraries/script-engine/src/AssetScriptingInterface.cpp
+++ b/libraries/script-engine/src/AssetScriptingInterface.cpp
@@ -419,7 +419,7 @@ void AssetScriptingInterface::compressData(QScriptValue options, QScriptValue sc
* false to upload and store the data without gzip compression. Synonym: compressed.
* @property {string|ArrayBuffer} data - The content to upload.
* @property {string} [path] - A user-friendly path for the file in the asset server. May have a leading
- * "atp:". IF not specified, no path-to-hash mapping is set.
+ * "atp:". If not specified, no path-to-hash mapping is set.
* Note: The asset server destroys any unmapped SHA256-named file at server restart. Either set the mapping path * with this property or use {@link Assets.setMapping} to set a path-to-hash mapping for the uploaded file.
*/ diff --git a/libraries/script-engine/src/ModelScriptingInterface.h b/libraries/script-engine/src/ModelScriptingInterface.h index 3c239f006f..39170bb370 100644 --- a/libraries/script-engine/src/ModelScriptingInterface.h +++ b/libraries/script-engine/src/ModelScriptingInterface.h @@ -17,19 +17,79 @@ #includeModel API provides the ability to manipulate meshes. You can get the meshes for an entity using
+ * {@link Entities.getMeshes}, or create a new mesh using {@link Model.newMesh}.
+ * See also, the {@link Graphics} API.
+ * + * @namespace Model + * + * @hifi-interface + * @hifi-client-entity + * @hifi-avatar + * @hifi-server-entity + * @hifi-assignment-client + * + * @deprecated This API is deprecated. Use the {@link Graphics} API instead. + */ class ModelScriptingInterface : public QObject { Q_OBJECT public: ModelScriptingInterface(QObject* parent); + /**jsdoc + * Exports meshes to an OBJ format model. + * @function Model.meshToOBJ + * @param {MeshProxy[]} meshes - The meshes to export. + * @returns {string} The OBJ format representation of the meshes. + */ Q_INVOKABLE QString meshToOBJ(MeshProxyList in); + + /**jsdoc + * Combines multiple meshes into one. + * @function Model.appendMeshes + * @param {MeshProxy[]} meshes - The meshes to combine. + * @returns {MeshProxy} The combined mesh. + */ Q_INVOKABLE QScriptValue appendMeshes(MeshProxyList in); + + /**jsdoc + * Transforms the vertices in a mesh. + * @function Model.transformMesh + * @param {Mat4} transform - The transform to apply. + * @param {MeshProxy} mesh - The mesh to apply the transform to. + * @returns {MeshProxy|boolean} The transformed mesh, if valid.false if an error.
+ */
Q_INVOKABLE QScriptValue transformMesh(glm::mat4 transform, MeshProxy* meshProxy);
+
+ /**jsdoc
+ * Creates a new mesh.
+ * @function Model.newMesh
+ * @param {Vec3[]} vertices - The vertices in the mesh.
+ * @param {Vec3[]} normals - The normals in the mesh.
+ * @param {MeshFace[]} faces - The faces in the mesh.
+ * @returns {MeshProxy} A new mesh.
+ */
Q_INVOKABLE QScriptValue newMesh(const QVectorfalse if an error.
+ */
Q_INVOKABLE QScriptValue getVertexCount(MeshProxy* meshProxy);
+
+ /**jsdoc
+ * Gets the position of a vertex in a mesh.
+ * @function Model.getVertex
+ * @param {MeshProxy} mesh - The mesh.
+ * @param {number} index - The index of the vertex to get.
+ * @returns {Vec3|boolean} The local position of the vertex relative to the mesh, if valid. false if an error.
+ */
Q_INVOKABLE QScriptValue getVertex(MeshProxy* meshProxy, int vertexIndex);
private:
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::functionThe 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 Name | Entity Event | |
|---|---|---|
| Event Name | Callback Type | Entity 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} |
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. * @exampleConstructed by new WebSocket(...) in Interface, client entity, avatar, and server entity scripts, or the
+ *
Create using new WebSocket(...) in Interface, client entity, avatar, and server entity scripts, or the
* {@link WebSocketServer} class in server entity and assignment client scripts.
*
*
Note: Does not support secure, wss: protocol.
Create using new WebSocketServer(...).
Create using new XMLHttpRequest(...).
OverlayWebWindow displays an HTML window inside Interface.
*
+ * Create using new OverlayWebWindow(...).
Create using new OverlayWindow(...).
Retrieve an existing tablet or create a new tablet using {@link Tablet.getTablet}.
* * @class TabletProxy + * @hideconstructor * * @hifi-interface * @hifi-client-entity @@ -422,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.
Create a new button using {@link TabletProxy#addButton}.
* * @class TabletButtonProxy + * @hideconstructor * * @hifi-interface * @hifi-client-entity diff --git a/tools/jsdoc/hifi-jsdoc-template/tmpl/container.tmpl b/tools/jsdoc/hifi-jsdoc-template/tmpl/container.tmpl index fccf5f7d31..9a4695e21c 100644 --- a/tools/jsdoc/hifi-jsdoc-template/tmpl/container.tmpl +++ b/tools/jsdoc/hifi-jsdoc-template/tmpl/container.tmpl @@ -75,7 +75,7 @@ - +