From 5256f5852062520755c7598c75717028cd6e8dc7 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 17 Dec 2019 16:17:45 +1300 Subject: [PATCH 01/24] Document callback function signatures for Script.addEventHandler() --- libraries/script-engine/src/ScriptEngine.cpp | 62 +++++++++++++++----- libraries/script-engine/src/ScriptEngine.h | 8 +-- 2 files changed, 50 insertions(+), 20 deletions(-) diff --git a/libraries/script-engine/src/ScriptEngine.cpp b/libraries/script-engine/src/ScriptEngine.cpp index 7e3f556c2d..9141b5e1c7 100644 --- a/libraries/script-engine/src/ScriptEngine.cpp +++ b/libraries/script-engine/src/ScriptEngine.cpp @@ -1009,6 +1009,12 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString& }); // Two common cases of event handler, differing only in argument signature. + + /**jsdoc + * Called when an entity event occurs on an entity as registered with {@link Script.addEventHandler}. + * @callback Script~entityEventCallback + * @param {Uuid} entityID - The ID of the entity the event has occured on. + */ using SingleEntityHandler = std::function; auto makeSingleEntityHandler = [this](QString eventName) -> SingleEntityHandler { return [this, eventName](const EntityItemID& entityItemID) { @@ -1016,6 +1022,12 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString& }; }; + /**jsdoc + * Called when a pointer event occurs on an entity as registered with {@link Script.addEventHandler}. + * @callback Script~pointerEventCallback + * @param {Uuid} entityID - The ID of the entity the event has occurred on. + * @param {PointerEvent} pointerEvent - Details of the event. + */ using PointerHandler = std::function; auto makePointerHandler = [this](QString eventName) -> PointerHandler { return [this, eventName](const EntityItemID& entityItemID, const PointerEvent& event) { @@ -1025,6 +1037,13 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString& }; }; + /**jsdoc + * Called when a collision event occurs on an entity as registered with {@link Script.addEventHandler}. + * @callback Script~collisionEventCallback + * @param {Uuid} entityA - The ID of one entity in the collision. + * @param {Uuid} entityB - The ID of the other entity in the collision. + * @param {Collision} collisionEvent - Details of the collision. + */ using CollisionHandler = std::function; auto makeCollisionHandler = [this](QString eventName) -> CollisionHandler { return [this, eventName](const EntityItemID& idA, const EntityItemID& idB, const Collision& collision) { @@ -1034,28 +1053,39 @@ void ScriptEngine::addEventHandler(const EntityItemID& entityID, const QString& }; /**jsdoc - *

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

+ *

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

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

See also, the {@link Entities} API.

* @function Script.addEventHandler * @param {Uuid} entityID - The ID of the entity. - * @param {Script.EntityEvent} eventName - The name of the entity event. - * @param {function} handler - The function to call when the entity event occurs on the entity. It can be either the name - * of a function or an in-line definition. + * @param {Script.EntityEvent} eventName - The name of the event. + * @param {Script~entityEventCallback|Script~pointerEventCallback|Script~collisionEventCallback} handler - The function to + * call when the event occurs on the entity. It can be either the name of a function or an in-line definition. * @example Report when a mouse press occurs on a particular entity. * var entityID = Entities.addEntity({ * type: "Box", From 7cf216f114afd8d057942e7703fe34b87da9010d Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 18 Dec 2019 07:15:34 +1300 Subject: [PATCH 02/24] Add warning about EventBridge not immediately availble in TabletProxy --- libraries/ui/src/ui/TabletScriptingInterface.h | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/libraries/ui/src/ui/TabletScriptingInterface.h b/libraries/ui/src/ui/TabletScriptingInterface.h index 04222b3ea1..3f834cab40 100644 --- a/libraries/ui/src/ui/TabletScriptingInterface.h +++ b/libraries/ui/src/ui/TabletScriptingInterface.h @@ -422,6 +422,12 @@ public: * 
EventBridge.scriptEventReceived.connect(function(message) {
      *     ...
      * });
+ *

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

* @function TabletProxy#emitScriptEvent * @param {string|object} message - The message to send to the web page. */ From c86ef990db07230645fa0f4fe07bf93ed71db54e Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 18 Dec 2019 07:27:53 +1300 Subject: [PATCH 03/24] Fix up JSDoc for Window.minimizedChanged signal --- interface/src/scripting/WindowScriptingInterface.h | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/interface/src/scripting/WindowScriptingInterface.h b/interface/src/scripting/WindowScriptingInterface.h index f3e9dea45f..bf39073db1 100644 --- a/interface/src/scripting/WindowScriptingInterface.h +++ b/interface/src/scripting/WindowScriptingInterface.h @@ -818,8 +818,12 @@ signals: /**jsdoc * Triggered when "minimized" state of the Interface window changes. * @function Window.minimizedChanged - * @param {bool} isMinimized - true if the Interface window is now minimized; false otherwise. + * @param {boolean} isMinimized - true if the Interface window is minimized, false if it isn't. * @returns {Signal} + * @example Report the "minimized" state of the Interface window when it changes. + * function onWindowMinimizedChanged(minimized) { + * print("Window minimized: " + minimized); + * } * * Window.minimizedChanged.connect(onWindowMinimizedChanged); */ From 34958ddb715bc72a49832a8c4813555fde078cc4 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 18 Dec 2019 08:01:20 +1300 Subject: [PATCH 04/24] Address some JSDoc issues identified by makitsune --- interface/src/AvatarBookmarks.cpp | 2 +- interface/src/avatar/MyAvatar.h | 2 +- interface/src/raypick/PointerScriptingInterface.h | 2 +- libraries/avatars/src/AvatarData.h | 3 ++- libraries/controllers/src/controllers/ScriptingInterface.h | 2 +- libraries/shared/src/JointData.h | 1 + 6 files changed, 7 insertions(+), 5 deletions(-) diff --git a/interface/src/AvatarBookmarks.cpp b/interface/src/AvatarBookmarks.cpp index 8f666ddbfa..9204cd7514 100644 --- a/interface/src/AvatarBookmarks.cpp +++ b/interface/src/AvatarBookmarks.cpp @@ -187,7 +187,7 @@ void AvatarBookmarks::updateAvatarEntities(const QVariantList &avatarEntities) { * @property {number} avatarScale - The target scale of the avatar. * @property {Array>} [avatarEntites] - The avatar entities included with the * bookmark. - * @property {MyAvatar.AttachmentData[]} [attachments] - The attachments included with the bookmark. + * @property {AttachmentData[]} [attachments] - The attachments included with the bookmark. *

Deprecated: Use avatar entities instead. */ diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index fc857bb11c..a5f26e7085 100644 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -1928,7 +1928,7 @@ public: * @param {boolean} isActive - true if flow simulation is enabled on the joint, false if it isn't. * @param {boolean} isCollidable - true to enable collisions in the flow simulation, false to * disable. - * @param {Object} [physicsConfig>] - Physics configurations for particular entity + * @param {Object} [physicsConfig] - Physics configurations for particular entity * and avatar joints. * @param {Object} [collisionsConfig] - Collision configurations for particular * entity and avatar joints. 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/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index 981882bf98..854ecb9ec3 100755 --- a/libraries/avatars/src/AvatarData.h +++ b/libraries/avatars/src/AvatarData.h @@ -1174,7 +1174,7 @@ public: /**jsdoc * @function Avatar.updateAvatarEntity * @param {Uuid} entityID - The entity ID. - * @param {Array.} entityData - Entity data. + * @param {ArrayBuffer} entityData - Entity data. * @deprecated This function is deprecated and will be removed. */ Q_INVOKABLE virtual void updateAvatarEntity(const QUuid& entityID, const QByteArray& entityData); @@ -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/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/shared/src/JointData.h b/libraries/shared/src/JointData.h index 7a2420262a..3f957fa046 100644 --- a/libraries/shared/src/JointData.h +++ b/libraries/shared/src/JointData.h @@ -16,6 +16,7 @@ public: // Used by the avatar mixer to describe a single joint // Translations relative to their parent joint // Rotations are absolute (i.e. not relative to parent) and are in rig space. +// No JSDoc because its not provided as a type to the script engine. class JointData { public: glm::quat rotation; From 28f5046ab2c533d8bd6a2f7dd4dfc68bcf900b05 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 18 Dec 2019 08:31:57 +1300 Subject: [PATCH 05/24] Fix MyAvatar.gotoLocation()'s "withSafeLanding" parameter JSDoc --- interface/src/avatar/MyAvatar.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index a5f26e7085..e694f0b8a9 100644 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -2072,8 +2072,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(), From 13a8ede1ac8d240b4922cc82f17470f76556be13 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 18 Dec 2019 09:19:26 +1300 Subject: [PATCH 06/24] Fix up MyAvatar reaction methods' JSDoc --- interface/src/avatar/MyAvatar.h | 62 +++++++++++++++++++-------------- 1 file changed, 36 insertions(+), 26 deletions(-) diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index e694f0b8a9..4367beb146 100644 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -1839,12 +1839,13 @@ public: Q_INVOKABLE void releaseEyesLookAtControl(); /**jsdoc - * Aims the pointing directional blending towards the provided target point. The "point" reaction should be triggered - * before using this method with the code MyAvatar.beginReaction("point"). - * @function MyAvatar.setPointAt - * @param {Vec3} pointAtTarget - The target point in world coordinates. - * @returns {boolean} true if the target point lays in front of the avatar, false if it doesn't. - */ + * Sets the point-at target for the "point" reaction that may be started with {@link MyAvatar.beginReaction}. + * The point-at target is set only if it is in front of the avatar. + *

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

+ * @function MyAvatar.setPointAt + * @param {Vec3} pointAtTarget - The target to point at, in world coordinates. + * @returns {boolean} true if the target point was set, false if it wasn't. + */ Q_INVOKABLE bool setPointAt(const glm::vec3& pointAtTarget); glm::quat getLookAtRotation() { return _lookAtYaw * _lookAtPitch; } @@ -2348,43 +2349,52 @@ public slots: virtual void setModelScale(float scale) override; /**jsdoc - * MyAvatar.getTriggerReactions - * Returns a list of reactions names that can be triggered using MyAvatar.triggerReaction(). - * @returns {string[]} Array of reaction names. + * Gets the list of reactions names that can be triggered using {@link MyAvatar.triggerReaction}. + *

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

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

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

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

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

+ * @function MyAvatar.beginReaction + * @param {string} reactionName - The reaction to start playing. + * @returns {boolean} true if the reaction was started, false if the reaction is not supported. */ bool beginReaction(QString reactionName); /**jsdoc - * MyAvatar.endReaction - * Used to stop a given reaction that was started via MyAvatar.beginReaction(). - * @param {string} reactionName - reaction name - * @returns {bool} false if the given reaction is not supported. + * Stops playing a reaction that was started using {@link MyAvatar.beginReaction}. + * @function MyAvatar.endReaction + * @param {string} reactionName - The reaction to stop playing. + * @returns {boolean} true if the reaction was stopped, false if the reaction is not supported. */ bool endReaction(QString reactionName); From 427aa851b34783e9bc1fa833795627c891f685b0 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 18 Dec 2019 09:51:34 +1300 Subject: [PATCH 07/24] Fix up links to avatar standards guide --- interface/src/avatar/MyAvatar.h | 4 ++-- libraries/avatars-renderer/src/avatars-renderer/Avatar.h | 4 ++-- libraries/avatars/src/AvatarData.h | 8 ++++---- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index 4367beb146..e8d6303526 100644 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -657,7 +657,7 @@ public: *

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

+ * Avatar Standards.

* @function MyAvatar.overrideAnimation * @param {string} url - The URL to the animation file. Animation files may be in glTF or FBX format, but only need to * contain the avatar skeleton and animation data. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs @@ -765,7 +765,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 diff --git a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h index 9c57fa36ae..e68edb3c9b 100644 --- a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h +++ b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h @@ -207,7 +207,7 @@ public: /**jsdoc * Gets the default rotation of a joint (in the current avatar) relative to its parent. *

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

+ * Avatar Standards.

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

Warning: These coordinates are not necessarily in meters.

*

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

+ * Avatar Standards.

* @function MyAvatar.getDefaultJointTranslation * @param {number} index - The joint index. * @returns {Vec3} The default translation of the joint (in model coordinates) if the joint index is valid, otherwise diff --git a/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index 854ecb9ec3..241ebe91c4 100755 --- a/libraries/avatars/src/AvatarData.h +++ b/libraries/avatars/src/AvatarData.h @@ -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. From 9d67b4aff2c3f8ad72f320f4da9c718a24843e02 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 18 Dec 2019 10:02:03 +1300 Subject: [PATCH 08/24] Fix up MyAvatar JSDoc on sitting property and methods --- interface/src/avatar/MyAvatar.h | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index e8d6303526..5d76cdfe41 100644 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -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. @@ -1953,8 +1953,8 @@ public: /**jsdoc * Starts a sitting action for the avatar. * @function MyAvatar.beginSit - * @param {Vec3} position - The point in space where the avatar will sit. - * @param {Quat} rotation - Initial absolute orientation of the avatar once is seated. + * @param {Vec3} position - The position where the avatar should sit. + * @param {Quat} rotation - The initial orientation of the seated avatar. */ Q_INVOKABLE void beginSit(const glm::vec3& position, const glm::quat& rotation); @@ -1962,15 +1962,14 @@ public: * Ends a sitting action for the avatar. * @function MyAvatar.endSit * @param {Vec3} position - The position of the avatar when standing up. - * @param {Quat} rotation - The absolute rotation of the avatar once the sitting action ends. + * @param {Quat} rotation - The orientation of the avatar when standing up. */ Q_INVOKABLE void endSit(const glm::vec3& position, const glm::quat& rotation); /**jsdoc - * Gets whether the avatar is in a seated pose. The seated pose is set by calling the - * MyAvatar::beginSit method. + * Gets whether the avatar is in a seated pose. The seated pose is set by calling {@link MyAvatar.beginSit}. * @function MyAvatar.isSeated - * @returns {boolean} true if the avatar is in a seated pose. + * @returns {boolean} true if the avatar is in a seated pose, false if it isn't. */ Q_INVOKABLE bool isSeated() { return _characterController.getSeated(); } From aa077684f57c1de079f8997840aa2851803c1ffb Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 18 Dec 2019 12:20:05 +1300 Subject: [PATCH 09/24] Update Controller.Hardware.Keyboard JSDoc per new touchpad gestures --- .../src/input-plugins/KeyboardMouseDevice.cpp | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/libraries/input-plugins/src/input-plugins/KeyboardMouseDevice.cpp b/libraries/input-plugins/src/input-plugins/KeyboardMouseDevice.cpp index b1b8875804..c436a5b510 100755 --- a/libraries/input-plugins/src/input-plugins/KeyboardMouseDevice.cpp +++ b/libraries/input-plugins/src/input-plugins/KeyboardMouseDevice.cpp @@ -356,17 +356,17 @@ controller::Input KeyboardMouseDevice::InputDevice::makeInput(KeyboardMouseDevic * new x-coordinate value. * MouseYnumbernumberThe mouse y-coordinate changed. The data value is its * new y-coordinate value. - * MouseWheelRightnumbernumberThe mouse wheel rotated right. The data value - * is the number of units rotated (typically 1.0). - * MouseWheelLeftnumbernumberThe mouse wheel rotated left. The data value - * is the number of units rotated (typically 1.0). - * MouseWheelUpnumbernumberThe mouse wheel rotated up. The data value - * is the number of units rotated (typically 1.0). + * MouseWheelRightnumbernumberThe mouse wheel rotated right or two-finger + * swipe moved right. The data value is the number of units moved (typically 1.0). + * MouseWheelLeftnumbernumberThe mouse wheel rotated left or two-finger + * swipe moved left. The data value is the number of units moved (typically 1.0). + * MouseWheelUpnumbernumberThe mouse wheel rotated up or two-finger swipe + * moved up. The data value is the number of units move3d (typically 1.0). *

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

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

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

* @@ -378,7 +378,11 @@ controller::Input KeyboardMouseDevice::InputDevice::makeInput(KeyboardMouseDevic * moved up. The data value is how far the average position of all touch points moved. * TouchpadDownnumbernumberThe average touch on a touch-enabled device * moved down. The data value is how far the average position of all touch points moved. - * + * GesturePinchOutnumbernumberThe average of two touches on a touch-enabled + * device moved out. The data value is how far the average positions of the touch points moved out. + * GesturePinchOutnumbernumberThe average of two touches on a touch-enabled + * device moved in. The data value is how far the average positions of the touch points moved in. + * * * @typedef {object} Controller.Hardware-Keyboard */ From a6b4bc587225cc15a4b4b143a9c64c298afa397c Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 18 Dec 2019 12:30:50 +1300 Subject: [PATCH 10/24] Revise recent Picks.PICK_BYPASS_IGNORE JSDoc --- interface/src/raypick/PickScriptingInterface.h | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) 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. From ccc4be5312bae699cfe5697248b1b6668c3d45f5 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Wed, 18 Dec 2019 12:54:56 +1300 Subject: [PATCH 11/24] Revise extended avatar blend shapes JSDoc --- interface/src/avatar/MyAvatar.h | 33 ++++++++++++++---------------- libraries/avatars/src/AvatarData.h | 28 ++++++++++++------------- 2 files changed, 29 insertions(+), 32 deletions(-) diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index 5d76cdfe41..5bf6461dab 100644 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -148,21 +148,21 @@ class MyAvatar : public Avatar { * size in the virtual world. Read-only. * @property {boolean} hasPriority - true if the avatar is in a "hero" zone, false if it isn't. * Read-only. - * @property {boolean} hasScriptedBlendshapes=false - true if blend shapes are controlled by scripted actions, - * otherwise false. Set this to true before using the {@link MyAvatar.setBlendshape} method, + * @property {boolean} hasScriptedBlendshapes=false - true if blend shapes are controlled by scripted actions, + * otherwise false. Set this to true before using the {@link MyAvatar.setBlendshape} method, * and set back to false after you no longer want scripted control over the blend shapes. - *

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

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

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

+ * @property {boolean} hasProceduralBlinkFaceMovement=true - true if avatars blink automatically by animating + * facial blend shapes, false if automatic blinking is disabled. Set this property to false + * to fully control the blink facial blend shapes via the {@link MyAvatar.setBlendshape} method. + * @property {boolean} hasProceduralEyeFaceMovement=true - true if the facial blend shapes for an avatar's eyes + * adjust automatically as the eyes move, false if this automatic movement is disabled. Set this property + * to true to prevent the iris from being obscured by the upper or lower lids. Set this property to + * false to fully control the eye blend shapes via the {@link MyAvatar.setBlendshape} method. + * @property {boolean} hasAudioEnabledFaceMovement=true - true if the avatar's mouth blend shapes animate + * automatically based on detected microphone input, false if this automatic movement is disabled. Set + * this property to false to fully control the mouth facial blend shapes via the * {@link MyAvatar.setBlendshape} method. * * @comment IMPORTANT: This group of properties is copied from Avatar.h; they should NOT be edited here. @@ -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 diff --git a/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index 241ebe91c4..24808b98bf 100755 --- a/libraries/avatars/src/AvatarData.h +++ b/libraries/avatars/src/AvatarData.h @@ -533,21 +533,21 @@ class AvatarData : public QObject, public SpatiallyNestable { * @property {boolean} hasPriority - true if the avatar is in a "hero" zone, false if it isn't. * Read-only. * @property {boolean} hasScriptedBlendshapes=false - true if blend shapes are controlled by scripted actions, - * otherwise false. Set this to true before using the {@link MyAvatar.setBlendshape} method, + * otherwise false. Set this to true before using the {@link Avatar.setBlendshape} method, * and set back to false after you no longer want scripted control over the blend shapes. - *

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

+ *

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

* @property {boolean} hasProceduralBlinkFaceMovement=true - true if avatars blink automatically by animating - * facial blend shapes, false if automatic blinking is disabled. Set this property to false if - * you wish to fully control the blink facial blend shapes via the {@link MyAvatar.setBlendshape} method. + * facial blend shapes, false if automatic blinking is disabled. Set this property to false + * to fully control the blink facial blend shapes via the {@link Avatar.setBlendshape} method. * @property {boolean} hasProceduralEyeFaceMovement=true - true if the facial blend shapes for an avatar's eyes * adjust automatically as the eyes move, false if this automatic movement is disabled. Set this property * to true to prevent the iris from being obscured by the upper or lower lids. Set this property to - * false if you wish to fully control the eye blend shapes via the {@link MyAvatar.setBlendshape} method. + * false to fully control the eye blend shapes via the {@link Avatar.setBlendshape} method. * @property {boolean} hasAudioEnabledFaceMovement=true - true if the avatar's mouth blend shapes animate * automatically based on detected microphone input, false if this automatic movement is disabled. Set - * this property to false if you wish to fully control the mouth facial blend shapes via the - * {@link MyAvatar.setBlendshape} method. + * this property to false to fully control the mouth facial blend shapes via the + * {@link Avatar.setBlendshape} method. */ Q_PROPERTY(glm::vec3 position READ getWorldPosition WRITE setPositionViaScript) Q_PROPERTY(float scale READ getDomainLimitedScale WRITE setTargetScale) @@ -1134,8 +1134,8 @@ public: /**jsdoc * Sets the value of a blend shape to animate your avatar's face. In order for other users to see the resulting animations - * on your avatar's face, set {@link Avatar.hasScriptedBlendshapes} to true. When you are done using this API, - * set {@link Avatar.hasScriptedBlendshapes} back to false when the animation is complete. + * on your avatar's face, set hasScriptedBlendshapes to true. When you are done using this API, + * set hasScriptedBlendshapes back to false when the animation is complete. * @function Avatar.setBlendshape * @param {string} name - The name of the blendshape, per the * {@link https://docs.highfidelity.com/create/avatars/avatar-standards.html#blendshapes Avatar Standards}. @@ -1188,12 +1188,12 @@ public: Q_INVOKABLE virtual void clearAvatarEntity(const QUuid& entityID, bool requiresRemovalFromTree = true); /**jsdoc - *

Deprecated: This method is deprecated and will be removed.

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

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

* @function Avatar.setForceFaceTrackerConnected - * @param {boolean} connected - true to enable blendshape changes to be transmitted to other users, + * @param {boolean} connected - true to enable blend shape changes to be transmitted to other users, * false to disable. */ Q_INVOKABLE void setForceFaceTrackerConnected(bool connected) { setHasScriptedBlendshapes(connected); } From c52fa7a376bcc0ccbab28cb8ae919c6dbbc241e3 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 19 Dec 2019 10:30:40 +1300 Subject: [PATCH 12/24] Fix up InteractiveWindow JSDoc per recent changes --- .../scripting/DesktopScriptingInterface.cpp | 46 ++++------------ .../src/scripting/DesktopScriptingInterface.h | 6 +-- interface/src/ui/InteractiveWindow.cpp | 39 +++++++++++--- interface/src/ui/InteractiveWindow.h | 54 ++++++++++++++++++- 4 files changed, 97 insertions(+), 48 deletions(-) diff --git a/interface/src/scripting/DesktopScriptingInterface.cpp b/interface/src/scripting/DesktopScriptingInterface.cpp index ae4af48cd6..f78f7853ca 100644 --- a/interface/src/scripting/DesktopScriptingInterface.cpp +++ b/interface/src/scripting/DesktopScriptingInterface.cpp @@ -30,21 +30,6 @@ * @property {InteractiveWindow.DockArea} LEFT - Dock to the left edge of the Interface window. * @property {InteractiveWindow.DockArea} RIGHT - Dock to the right edge of the Interface window. */ -/**jsdoc - *

A docking location of an InteractiveWindow.

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

A display mode for an InteractiveWindow.

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

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

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

A display mode for an InteractiveWindow.

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

A docking location of an InteractiveWindow.

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

The anchor for a relative position of an InteractiveWindow.

+ * + * + * + * + * + * + * + * + * + * + * + *
ValueNameDescription
0NO_ANCHORPosition is not relative to any part of the Interface window.
1TOP_LEFTPosition is offset from the top left of the Interface window.
2TOP_RIGHTPosition is offset from the top right of the Interface window.
3BOTTOM_RIGHTPosition offset from the bottom right of the Interface + * window.
4BOTTOM_LEFFTPosition is offset from the bottom left of the Interface + * window.
+ * @typedef {number} InteractiveWindow.RelativePositionAnchor + */ enum RelativePositionAnchor { NO_ANCHOR, TOP_LEFT, @@ -116,7 +164,11 @@ using namespace InteractiveWindowEnums; * @hifi-avatar * * @property {string} title - The title of the window. - * @property {Vec2} position - The position of the window, in pixels. + * @property {Vec2} position - The absolute position of the window, in pixels. + * @property {InteractiveWindow.RelativePositionAnchor} relativePositionAnchor - The anchor for the + * relativePosition, if used. + * @property {Vec2} relativePosition - The position of the window, relative to the relativePositionAnchor, in + * pixels. Excludes the window frame. * @property {Vec2} size - The size of the window, in pixels. * @property {boolean} visible - true if the window is visible, false if it isn't. * @property {InteractiveWindow.PresentationMode} presentationMode - The presentation mode of the window: From e13b237e960cf0fd5c4aaf0c2735718638f5eca8 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 19 Dec 2019 11:23:36 +1300 Subject: [PATCH 13/24] Add missing Controller.Hardware.Application camera properties' JSDoc --- interface/src/Application.cpp | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/interface/src/Application.cpp b/interface/src/Application.cpp index 49e07ad658..36f1f4132a 100644 --- a/interface/src/Application.cpp +++ b/interface/src/Application.cpp @@ -693,10 +693,17 @@ private: * * * CameraFirstPersonnumbernumberThe camera is in first-person mode. - * + * Legacy first person camera mode. + * CameraFirstPersonLookAtnumbernumberThe camera is in first-person mode. + * Default first person camera mode. * CameraThirdPersonnumbernumberThe camera is in third-person mode. - * - * CameraFSMnumbernumberThe camera is in full screen mirror mode. + * Legacy third person camera mode. + * CameraLookAtnumbernumberThe camera is in third-person mode. + * Default third person camera mode. + * CameraFSMnumbernumberThe camera is in full screen mirror mode. + * Legacy "look at myself" behavior. + * CameraSelfienumbernumberThe camera is in selfie mode. + * Default "look at myself" camera mode. * CameraIndependentnumbernumberThe camera is in independent mode. * CameraEntitynumbernumberThe camera is in entity mode. * InHMDnumbernumberThe user is in HMD mode. From a04e57d82d158addb8ca62db833ee30de1288bab Mon Sep 17 00:00:00 2001 From: David Rowe Date: Thu, 19 Dec 2019 11:38:17 +1300 Subject: [PATCH 14/24] Miscellaneous JSDoc fixes noticed in passing --- interface/src/avatar/MyAvatar.h | 54 +++++++++---------- .../procedural/src/procedural/Procedural.h | 1 - libraries/ui/src/QmlWebWindowClass.h | 2 +- 3 files changed, 28 insertions(+), 29 deletions(-) diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index 5bf6461dab..7822b6a8f3 100644 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -527,7 +527,7 @@ public: * 0ForceSitAssumes the user is seated in the real world. Disables avatar * leaning regardless of what the avatar is doing in the virtual world (i.e., avatar always recenters). * 1ForceStandAssumes the user is standing in the real world. Enables avatar - * leaning regardless of what the avatar is doing in the virtual world (i.e. avatar leans, then if leans too far it + * leaning regardless of what the avatar is doing in the virtual world (i.e., avatar leans, then if leans too far it * recenters). * 2AutoInterface detects when the user is standing or seated in the real world. * Avatar leaning is disabled when the user is sitting (i.e., avatar always recenters), and avatar leaning is enabled @@ -1792,47 +1792,47 @@ 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 diff --git a/libraries/procedural/src/procedural/Procedural.h b/libraries/procedural/src/procedural/Procedural.h index 89f21218e6..9b3d0a9bd4 100644 --- a/libraries/procedural/src/procedural/Procedural.h +++ b/libraries/procedural/src/procedural/Procedural.h @@ -27,7 +27,6 @@ using UniformLambdas = std::list>; const size_t MAX_PROCEDURAL_TEXTURE_CHANNELS{ 4 }; /**jsdoc - * An object containing user-defined uniforms for communicating data to shaders. * @typedef {object} ProceduralUniforms */ diff --git a/libraries/ui/src/QmlWebWindowClass.h b/libraries/ui/src/QmlWebWindowClass.h index 3ca6418195..16e18f282f 100644 --- a/libraries/ui/src/QmlWebWindowClass.h +++ b/libraries/ui/src/QmlWebWindowClass.h @@ -106,7 +106,7 @@ * }, 2000); * * @example - * // HTML file, "OverlayWebWindow.qml". + * // HTML file, "OverlayWebWindow.html". * * * From 1ebc6a575e1fe7f8b38d22de0957a57cfba0c298 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 20 Dec 2019 13:33:48 +1300 Subject: [PATCH 15/24] Model API JSDoc --- .../src/ModelScriptingInterface.h | 60 +++++++++++++++++++ libraries/shared/src/RegisteredMetaTypes.cpp | 5 ++ 2 files changed, 65 insertions(+) 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 @@ #include class QScriptEngine; +/**jsdoc + * The Model 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 QVector& vertices, const QVector& normals, const QVector& faces); + + /**jsdoc + * Gets the number of vertices in a mesh. + * @function Model.getVertexCount + * @param {MeshProxy} mesh - The mesh to count the vertices in. + * @returns {number|boolean} The number of vertices in the mesh, if valid. false 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/shared/src/RegisteredMetaTypes.cpp b/libraries/shared/src/RegisteredMetaTypes.cpp index 87cd269c97..7c30d4f205 100644 --- a/libraries/shared/src/RegisteredMetaTypes.cpp +++ b/libraries/shared/src/RegisteredMetaTypes.cpp @@ -1306,6 +1306,11 @@ void meshesFromScriptValue(const QScriptValue& value, MeshProxyList &out) { } +/**jsdoc + * A triangle in a mesh. + * @typedef {object} MeshFace + * @property {number[]} vertices - The indexes of the three vertices that make up the fase. + */ QScriptValue meshFaceToScriptValue(QScriptEngine* engine, const MeshFace &meshFace) { QScriptValue obj = engine->newObject(); obj.setProperty("vertices", qVectorIntToScriptValue(engine, meshFace.vertexIndices)); From 8255a50cdec0fe1229bb2539fc780a17ad168107 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Fri, 20 Dec 2019 13:34:21 +1300 Subject: [PATCH 16/24] Update MeshProxy and Entities.getMeshes() JSDoc --- libraries/entities/src/EntityScriptingInterface.h | 6 ++++-- libraries/shared/src/RegisteredMetaTypes.h | 9 +++++---- 2 files changed, 9 insertions(+), 6 deletions(-) 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 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/shared/src/RegisteredMetaTypes.h b/libraries/shared/src/RegisteredMetaTypes.h index 3b47bb70c6..b8c2e9b1db 100644 --- a/libraries/shared/src/RegisteredMetaTypes.h +++ b/libraries/shared/src/RegisteredMetaTypes.h @@ -687,7 +687,8 @@ namespace graphics { using MeshPointer = std::shared_ptr; /**jsdoc - * A handle for a mesh in an entity, such as returned by {@link Entities.getMeshes}. + * A mesh, such as returned by {@link Entities.getMeshes} or {@link Model} API functions. + * * @class MeshProxy * * @hifi-interface @@ -705,16 +706,16 @@ public: virtual MeshPointer getMeshPointer() const = 0; /**jsdoc - * Get the number of vertices in the mesh. + * Gets the number of vertices in the mesh. * @function MeshProxy#getNumVertices * @returns {number} Integer number of vertices in the mesh. */ Q_INVOKABLE virtual int getNumVertices() const = 0; /**jsdoc - * Get the position of a vertex in the mesh. + * Gets the position of a vertex in the mesh. * @function MeshProxy#getPos - * @param {number} index - Integer index of the mesh vertex. + * @param {number} index - Integer index of the vertex. * @returns {Vec3} Local position of the vertex relative to the mesh. */ Q_INVOKABLE virtual glm::vec3 getPos(int index) const = 0; From eb11231e78be040102ab3548b4054fb50617fbb7 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Mon, 23 Dec 2019 09:07:35 +1300 Subject: [PATCH 17/24] Graphics API JSDoc --- .../src/graphics-scripting/Forward.h | 60 ++--- .../GraphicsScriptingInterface.cpp | 129 ++++++++- .../GraphicsScriptingInterface.h | 84 ++++-- .../GraphicsScriptingUtil.cpp | 18 ++ .../src/graphics-scripting/ScriptableMesh.cpp | 28 +- .../src/graphics-scripting/ScriptableMesh.h | 173 ++++++++++++- .../graphics-scripting/ScriptableMeshPart.h | 244 ++++++++++++++++-- .../src/graphics-scripting/ScriptableModel.h | 51 +++- .../src/graphics/BufferViewHelpers.cpp | 44 ++++ libraries/graphics/src/graphics/Geometry.h | 17 -- .../graphics/src/graphics/GpuHelpers.cpp | 18 ++ 11 files changed, 751 insertions(+), 115 deletions(-) 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_ptr; using WeakModelProviderPointer = std::weak_ptr; - /**jsdoc - * @typedef {object} Graphics.Material - * @property {string} name - * @property {string} model - * @property {number|string} opacity - * @property {number|string} roughness - * @property {number|string} metallic - * @property {number|string} scattering - * @property {boolean|string} unlit - * @propety {Vec3|string} emissive - * @propety {Vec3|string} albedo - * @property {string} emissiveMap - * @property {string} albedoMap - * @property {string} opacityMap - * @property {string} opacityMapMode - * @property {number|string} opacityCutoff - * @property {string} metallicMap - * @property {string} specularMap - * @property {string} roughnessMap - * @property {string} glossMap - * @property {string} normalMap - * @property {string} bumpMap - * @property {string} occlusionMap - * @property {string} lightMap - * @property {string} scatteringMap - * @property {Mat4|string} texCoordTransform0 - * @property {Mat4|string} texCoordTransform1 - * @property {string} lightmapParams - * @property {string} materialParams - * @property {string} cullFaceMode - * @property {boolean} defaultFallthrough - * @property {string} procedural - */ class ScriptableMaterial { public: ScriptableMaterial() {} @@ -110,9 +77,11 @@ namespace scriptable { }; /**jsdoc + * A material layer. * @typedef {object} Graphics.MaterialLayer - * @property {Graphics.Material} material - This layer's material. - * @property {number} priority - The priority of this layer. If multiple materials are applied to a mesh part, only the highest priority layer is used. + * @property {Graphics.Material} material - The layer's material. + * @property {number} priority - The priority of the layer. If multiple materials are applied to a mesh part, only the + * layer with the highest priority is applied, with materials of the same priority randomly assigned. */ class ScriptableMaterialLayer { public: @@ -138,8 +107,29 @@ namespace scriptable { ScriptableMeshBase(const ScriptableMeshBase& other, QObject* parent = nullptr) : QObject(parent) { *this = other; } ScriptableMeshBase& operator=(const ScriptableMeshBase& view); virtual ~ScriptableMeshBase(); + + /**jsdoc + * @function GraphicsMesh.getMeshPointer + * @deprecated This method is deprecated and will be removed. + * @returns {undefined} + */ + // scriptable::MeshPointer is not registered as a JavaScript type. Q_INVOKABLE const scriptable::MeshPointer getMeshPointer() const { return weakMesh.lock(); } + + /**jsdoc + * @function GraphicsMesh.getModelProviderPointer + * @deprecated This method is deprecated and will be removed. + * @returns {undefined} + */ + // scriptable::ModelProviderPointer is not registered as a JavaScript type. Q_INVOKABLE const scriptable::ModelProviderPointer getModelProviderPointer() const { return provider.lock(); } + + /**jsdoc + * @function GraphicsMesh.getModelBasePointer + * @deprecated This method is deprecated and will be removed. + * @returns {undefined} + */ + // scriptable::ScriptableModelBasePointer is not registered as a JavaScript type. Q_INVOKABLE const scriptable::ScriptableModelBasePointer getModelBasePointer() const { return model; } }; diff --git a/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingInterface.cpp b/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingInterface.cpp index 62614ea6e8..9d36cfd91a 100644 --- a/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingInterface.cpp +++ b/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingInterface.cpp @@ -168,14 +168,15 @@ scriptable::ScriptableMeshPointer GraphicsScriptingInterface::newMesh(const QVar // in the future we want to support a formal C++ structure data type here instead /**jsdoc + * IFS (Indexed-Face Set) data defining a mesh. * @typedef {object} Graphics.IFSData - * @property {string} [name=""] - mesh name (useful for debugging / debug prints). - * @property {string} [topology=""] - * @property {number[]} indices - vertex indices to use for the mesh faces. - * @property {Vec3[]} vertices - vertex positions (model space) - * @property {Vec3[]} [normals=[]] - vertex normals (normalized) - * @property {Vec3[]} [colors=[]] - vertex colors (normalized) - * @property {Vec2[]} [texCoords0=[]] - vertex texture coordinates (normalized) + * @property {string} [name=""] - Mesh name. (Useful for debugging.) + * @property {Graphics.MeshTopology} topology - Element interpretation. Currently only triangles is supported. + * @property {number[]} indices - Vertex indices to use for the mesh faces, in tuples per the topology. + * @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: + *
    + *
  • "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.
    • + *
+ * If "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. + *

Currently not used.

+ * @property {string} [scatteringMap] - The URL of the scattering texture image. + * If "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. + *

Currently not used.

+ * @property {string} [cullFaceMode="CULL_BACK"] - Specifies Which faces of the geometry to render. Values can be: + *
    + *
  • "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.
    • + *
+ * If "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. + *

Currently not used.

+ * + * @property {boolean} defaultFallthrough - 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. + *

Note: The model data may be used for more than one instance of the item displayed in the scene.

* @function Graphics.getModel - * @param {UUID} entityID - The objectID of the model whose meshes are to be retrieved. - * @returns {Graphics.Model} the resulting Model object + * @param {UUID} id - The ID of the avatar, 3D entity, or 3D overlay. + * @returns {GraphicsModel} The model data for the avatar, entity, or overlay, as displayed. This includes the results of + * applying any {@link Entities.EntityProperties-Material|Material} entities to the item. + * @example Report some details of your avatar's model. + * var model = Graphics.getModel(MyAvatar.sessionUUID); + * var meshes = model.meshes; + * var numMeshparts = 0; + * for (var i = 0; i < meshes.length; i++) { + * numMeshparts += meshes[i].numParts; + * } + * + * print("Avatar:", MyAvatar.skeletonModelURL); + * print("Number of meshes:", model.numMeshes); + * print("Number of mesh parts:", numMeshparts); + * print("Material names: ", model.materialNames); + * print("Material layers:", Object.keys(model.materialLayers)); */ scriptable::ScriptableModelPointer getModel(const QUuid& uuid); /**jsdoc + * Updates the model for an avatar, 3D entity, or 3D overlay in the rendered scene. * @function Graphics.updateModel - * @param {Uuid} id - * @param {Graphics.Model} model - * @returns {boolean} + * @param {Uuid} id - The ID of the avatar, 3D entity, or 3D overlay to update. + * @param {GraphicsModel} model - The model to update the avatar, 3D entity, or 3D overlay with. + * @returns {boolean} 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 Test whether different types of items can be updated. + * var modelEntityID = Entities.addEntity({ + * type: "Model", + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(Camera.orientation, { x: -0.5, y: 0, z: -3 })), + * rotation: MyAvatar.orientation, + * modelURL: "http://content.highfidelity.com/seefo/production/puck-attach/vive_tracker_puck.obj", + * dimensions: { x: 0.945, y: 0.921, z: 0.423 }, + * lifetime: 300 // Delete after 5 minutes. + * }); + * var shapeEntityID = Entities.addEntity({ + * type: "Shape", + * shape: "Cylinder", + * position: Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(Camera.orientation, { x: 0.5, y: 0, z: -3 })), + * dimensions: { x: 0.4, y: 0.6, z: 0.4 }, + * lifetime: 300 // Delete after 5 minutes. + * }); + * + * Script.setTimeout(function () { + * print("Can update avatar:", Graphics.canUpdateModel(MyAvatar.sessionUUID)); // true + * print("Can update model entity:", Graphics.canUpdateModel(modelEntityID)); // true + * print("Can update shape entity:", Graphics.canUpdateModel(shapeEntityID)); // false + * }, 1000); // Wait for the entities to rez. */ bool canUpdateModel(const QUuid& uuid, int meshIndex = -1, int partNumber = -1); /**jsdoc + * Creates a new graphics model from meshes. * @function Graphics.newModel - * @param {Graphics.Mesh[]} meshes - * @returns {Graphics.Model} + * @param {GraphicsMesh[]} meshes - The meshes to include in the model. + * @returns {GraphicsModel} The new graphics model. */ scriptable::ScriptableModelPointer newModel(const scriptable::ScriptableMeshes& meshes); /**jsdoc - * Create a new Mesh / Mesh Part with the specified data buffers. - * + * Creates a new graphics mesh. * @function Graphics.newMesh - * @param {Graphics.IFSData} ifsMeshData Index-Faced Set (IFS) arrays used to create the new mesh. - * @returns {Graphics.Mesh} the resulting Mesh / Mesh Part object + * @param {Graphics.IFSData} ifsMeshData - Index-Faced Set (IFS) data defining the mesh. + * @returns {GraphicsMesh} The new graphics mesh. */ scriptable::ScriptableMeshPointer newMesh(const QVariantMap& ifsMeshData); @@ -89,10 +131,12 @@ public slots: #endif /**jsdoc + * Exports a model to OBJ format. * @function Graphics.exportModelToOBJ - * @param {Graphics.Model} model - * @returns {string} + * @param {GraphicsModel} model - The model to export. + * @returns {string} The OBJ format representation of the model. */ + // FIXME: If you put the OBJ on the Asset Server and rez it, Interface keeps crashing until the model is removed. QString exportModelToOBJ(const scriptable::ScriptableModelPointer& model); private: diff --git a/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingUtil.cpp b/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingUtil.cpp index da582b2d21..d1f419728a 100644 --- a/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingUtil.cpp +++ b/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingUtil.cpp @@ -37,6 +37,14 @@ QVariant toVariant(const Extents& box) { }; } +/**jsdoc + * The extents of a mesh. + * @typedef {object} Graphics.MeshExtents + * @property {Vec3} brn - The bottom right near (minimum axes values) corner of the enclosing box. + * @property {Vec3} tfl - The top far left (maximum axes values) corner of the enclosing box. + * @property {Vec3} center - The center of the enclosing box. + * @property {Vec3} dimensions - The dimensions of the enclosing box. + */ QVariant toVariant(const AABox& box) { return QVariantMap{ { "brn", glmVecToVariant(box.getCorner()) }, @@ -48,6 +56,16 @@ QVariant toVariant(const AABox& box) { }; } +/**jsdoc + * Details of a buffer element's format. + * @typedef {object} Graphics.BufferElementFormat + * @property {string} type + * @property {string} semantic + * @property {string} dimension + * @property {number} scalarCount + * @property {number} byteSize + * @property {number} BYTES_PER_ELEMENT + */ QVariant toVariant(const gpu::Element& element) { return QVariantMap{ { "type", gpu::toString(element.getType()) }, diff --git a/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.cpp b/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.cpp index 72d2adb48f..5f81e2daf7 100644 --- a/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.cpp +++ b/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.cpp @@ -127,6 +127,16 @@ int scriptable::ScriptableMesh::getSlotNumber(const QString& attributeName) cons return -1; } +/**jsdoc + * Details of buffer's format. + * @typedef {object} Graphics.BufferFormat + * @property {number} slot + * @property {number} length + * @property {number} byteLength + * @property {number} offset + * @property {number} stride + * @property {Graphics.BufferElementFormat} element + */ QVariantMap scriptable::ScriptableMesh::getBufferFormats() const { QVariantMap result; for (const auto& a : buffer_helpers::ATTRIBUTES.toStdMap()) { @@ -247,6 +257,13 @@ bool scriptable::ScriptableMesh::setVertexProperty(glm::uint32 vertexIndex, cons return buffer_helpers::setValue(bufferView, vertexIndex, value); } +/**jsdoc + * Called for each vertex when {@link GraphicsMesh.updateVertexAttributes} is called. + * @callback GraphicsMesh~forEachVertextCallback + * @param {Object} attributes - The attributes of the vertex. + * @param {number} index - The vertex index. + * @param {object} properties - The properties of the mesh, per {@link GraphicsMesh}. + */ glm::uint32 scriptable::ScriptableMesh::forEachVertex(QScriptValue _callback) { auto mesh = getMeshPointer(); if (!mesh) { @@ -275,7 +292,16 @@ glm::uint32 scriptable::ScriptableMesh::forEachVertex(QScriptValue _callback) { return numProcessed; } - +/**jsdoc + * Called for each vertex when {@link GraphicsMesh.updateVertexAttributes} is called. The value returned by the script function + * should be the modified attributes to update the vertex with, or false to not update the particular vertex. + * @callback GraphicsMesh~updateVertexAttributesCallback + * @param {Object} attributes - The attributes of the vertex. + * @param {number} index - The vertex index. + * @param {object} properties - The properties of the mesh, per {@link GraphicsMesh}. + * @returns {Object|boolean} The attribute values to update the vertex with, or + * false 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..98f496cd9e 100644 --- a/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.h +++ b/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.h @@ -1,4 +1,3 @@ -// // Copyright 2018 High Fidelity, Inc. // // Distributed under the Apache License, Version 2.0. @@ -29,17 +28,40 @@ 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}. + * + *

Created using the {@link Graphics} API, {@link GraphicsModel.cloneModel}, or {@link GraphicsMesh.cloneMesh}.

+ * + * @class GraphicsMesh + * + * @hifi-interface + * @hifi-client-entity + * @hifi-avatar + * + * @property {number} numParts - The number of mesh parts. + * Read-only. + * @property {GraphicsMeshPart[]} parts - The mesh parts. + * Read-only. + * @property {number} numIndices - The total number of vertex indices in the mesh. + * Read-only. + * @property {number} numVertices - The total number of vertices in the mesh. + * Read-only. + * @property {number} numAttributes - The number of vertex attributes. + * Read-only. + * @property {Graphics.BufferTypeName[]} attributeNames - The names of the vertex attributes. + * Read-only. + * @property {boolean} valid - 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 {Object} bufferFormats - Details of the buffers used for the + * mesh. + * Read-only. + * + * @borrows GraphicsMesh.getVertextAttributes as getVertextAttributes + * @borrows GraphicsMesh.setVertextAttributes as setVertextAttributes */ class ScriptableMesh : public ScriptableMeshBase, QScriptable { Q_OBJECT @@ -82,26 +104,153 @@ namespace scriptable { int getSlotNumber(const QString& attributeName) const; public slots: + + /**jsdoc + * Gets the model the mesh is part of. + *

Currently doesn't work.

+ * @function GraphicsMesh.getParentModel + * @returns {GraphicsModel} The model the mesh is part of, null if it isn't part of a model. + */ const scriptable::ScriptableModelPointer getParentModel() const { return qobject_cast(model); } + + /**jsdoc + * Gets the vertex indices. + * @function GraphicsMesh.getIndices + * @returns {number[]} The vertex indices. + */ QVector getIndices() const; + + /**jsdoc + * Gets the indices of nearby vertices. + * @function GraphicsMesh.findNearbyVertexIndices + * @param {Vec3} origin - The search position, in model coordinates. + * @param {number} [epsilon=1e-6] - The search distance. If a vertex is within this distance from the + * origin it is considered to be "nearby". + * @returns {number[]} The indices of nearby vertices. + */ QVector findNearbyVertexIndices(const glm::vec3& origin, float epsilon = 1e-6) const; + /**jsdoc + * Adds an attribute to the (whole) mesh's vertices. + * @function GraphicsMesh.addAttribute + * @param {Graphics.BufferTypeName} name - The name of the attribute. + * @param {Graphics.BufferType} [defaultValue] - The value to give the attributes added to the vertices. + * @returns {number} The number of vertices the attribute was added to, 0 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. + *

Note: The "position" attribute cannot be removed.

+ * @function GraphicsMesh.removeAttribute + * @param {Graphics.BufferTypeName} name - The name of the attribute to remove. + * @returns {boolean} 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 {Object} The attribute names and values for the vertex. + * @throws Throws an error if the index 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 {Object} values - The attribute names and values. Need not + * specify unchanged values. + * @returns {boolean} true 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..00645145c5 100644 --- a/libraries/graphics-scripting/src/graphics-scripting/ScriptableMeshPart.h +++ b/libraries/graphics-scripting/src/graphics-scripting/ScriptableMeshPart.h @@ -11,23 +11,49 @@ 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}. + * + *

Created using the {@link Graphics} API, {@link GraphicsModel.cloneModel}, {@link GraphicsMesh.cloneMesh}, or + * {@link GraphicsMeshPart.cloneMeshPart}.

+ * + * @class GraphicsMeshPart + * + * @hifi-interface + * @hifi-client-entity + * @hifi-avatar + * + * @property {boolean} valid - 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 {Object} bufferFormats - Details of the buffers used for the + * whole mesh (i.e., parent and mesh parts). + * Read-only. + * @borrows GraphicsMesh.addAttribute as addAttribute + * @borrows GraphicsMesh.getVertexAttributes as getVertextAttributes + * @borrows GraphicsMesh.setVertexAttributes as setVertextAttributes + */ class ScriptableMeshPart : public QObject, QScriptable { Q_OBJECT Q_PROPERTY(bool valid READ isValid) @@ -55,42 +81,228 @@ namespace scriptable { bool isValid() const { auto mesh = getMeshPointer(); return mesh && partIndex < mesh->getNumParts(); } public slots: + + /**jsdoc + * Gets the vertex indices. + * @function GraphicsMeshPart.getIndices + * @returns {number[]} The vertex indices. + */ QVector getIndices() const; + + /**jsdoc + * Sets the vertex indices. + * @function GraphicsMeshPart.setIndices + * @param {number[]} indices - The vertex indices. + * @returns {boolean} true 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 QVector& indices); + + /**jsdoc + * Gets the indices of nearby vertices in the mesh part. + * @function GraphicsMeshPart.findNearbyPartVertexIndices + * @param {Vec3} origin - The search position, in model coordinates. + * @param {number} [epsilon=1e-6] - The search distance. If a vertex is within this distance from the + * origin it is considered to be "nearby". + * @returns {number[]} The indices of nearby vertices. + */ QVector findNearbyPartVertexIndices(const glm::vec3& origin, float epsilon = 1e-6) const; + + /**jsdoc + * Gets the value of an attribute for all vertices in the whole mesh (i.e., parent and mesh parts). + * @function GraphicsMeshPArt.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; + + // @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. + */ QVector getFace(glm::uint32 faceIndex) const; + /**jsdoc + * Scales the mesh to so that it's maximum model coordinate dimension is a specified length. + * @function GraphicsMeshPart.scaleToFit + * @param {number} scale - The target dimension. + * @returns {Graphics.MeshExtents} The resulting mesh extents, in model coordinates. + */ QVariantMap scaleToFit(float unitScale); + + /**jsdoc + * Translates the mesh part. + * @function GraphicsMeshPart.translate + * @param {Vec3} translation - The translation to apply, in model coordinates. + * @returns {Graphics.MeshExtents} The rseulting mesh extents, in model coordinates. + */ QVariantMap translate(const glm::vec3& translation); + + /**jsdoc + * Scales the mesh part. + * @function GraphicsMeshPart.scale + * @param {Vec3} scale - The scale to apply in each model coordinate direction. + * @param {Vec3} [origin] - The origin to scale about. If not specified, the center of the mesh part is used. + * @returns {Graphics.MeshExtents} The resulting mesh extents, in model coordinates. + */ QVariantMap scale(const glm::vec3& scale, const glm::vec3& origin = glm::vec3(NAN)); + + /**jsdoc + * Rotates the mesh part, using Euler angles. + * @function GraphicsMeshPart.rotateDegrees + * @param {Vec3} eulerAngles - The rotation to perform, in mesh coordinates, as Euler angles in degrees. + * @param {Vec3} [origin] - The point about which to rotate, in model coordinates. + *

Warning: Currently doesn't work as expected.

+ * @returns {Graphics.MeshExtents} The resulting mesh extents, in model coordinates. + */ QVariantMap rotateDegrees(const glm::vec3& eulerAngles, const glm::vec3& origin = glm::vec3(NAN)); + + /**jsdoc + * Rotates the mesh part, using a quaternion. + * @function GraphicsMeshPart.rotate + * @param {Quat} rotation - The rotation to perform, in model coordinates. + * @param {Vec3} [origin] - The point about which to rotate, in model coordinates. + *

Warning: Currently doesn't work as expected.

+ * @returns {Graphics.MeshExtents} The resulting mesh extents, in model coordinates. + */ QVariantMap rotate(const glm::quat& rotation, const glm::vec3& origin = glm::vec3(NAN)); + + /**jsdoc + * Scales, rotates, and translates the mesh. + * @function GraphicsMeshPart.transform + * @param {Mat4} transform - The scale, rotate, and translate transform to apply. + * @returns {Graphics.MeshExtents} The resulting mesh extents, in model coordinates. + */ QVariantMap transform(const glm::mat4& transform); + // @borrows jsdoc from GraphicsMesh. glm::uint32 addAttribute(const QString& attributeName, const QVariant& defaultValue = QVariant()); + + /**jsdoc + * Sets the value of an attribute for all vertices in the whole mesh (i.e., parent and mesh parts). + * @function GraphicsMeshPart.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 in the whole mesh (i.e., parent and mesh parts). + *

Note: The "position" attribute cannot be removed.

+ * @function GraphicsMeshPArt.removeAttribute + * @param {Graphics.BufferTypeName} name - The name of the attribute to remove. + * @returns {boolean} 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 QVector& attributeNames = QVector()); + + /**jsdoc + * Makes a copy of the mesh part. + * @function GraphicsMeshPart.cloneMeshPart + * @returns {GraphicsMeshPart} A copy of the mesh part. + */ scriptable::ScriptableMeshPartPointer cloneMeshPart(); + /**jsdoc + * Exports the mesh part to OBJ format. + * @function GraphicsMeshPart.toOBJ + * @returns {string} The OBJ format representation of the mesh part. + */ QString toOBJ(); + // QScriptEngine-specific wrappers + + /**jsdoc + * Updates vertex attributes by calling a function for each vertex in the whole mesh (i.e., the parent and + * mesh parts). The function can return modified attributes to update the vertex with. + * @function GraphicsMeshPart.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 in the whole mesh (i.e., parent and mesh parts). + * @function GraphicsMeshPArt.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 GraphicsMeshPart.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; + 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..faa65f8bf6 100644 --- a/libraries/graphics-scripting/src/graphics-scripting/ScriptableModel.h +++ b/libraries/graphics-scripting/src/graphics-scripting/ScriptableModel.h @@ -17,14 +17,35 @@ namespace scriptable { using ScriptableMeshes = QVector; /**jsdoc - * @typedef {object} Graphics.Model - * @property {Uuid} objectID - UUID of corresponding inworld object (if model is associated) - * @property {number} numMeshes - The number of submeshes contained in the model. - * @property {Graphics.Mesh[]} meshes - Array of submesh references. - * @property {Object.} materialLayers - Map of materials layer lists. You can look up a material layer list by mesh part number or by material name. - * @property {string[]} materialNames - Array of all the material names used by the mesh parts of this model, in order (e.g. materialNames[0] is the name of the first mesh part's material). + * A handle to in-memory model data such as may be used in displaying avatars, 3D entities, or 3D overlays in the rendered + * scene. Changes made to the model are visible only to yourself; they are not persisted. + *

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}.

+ * + * @class GraphicsModel + * + * @hifi-interface + * @hifi-client-entity + * @hifi-avatar + * + * @property {Uuid} objectID - The ID of the entity or avatar that the model is associated with, if any; null + * 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.} materialLayers - The mapping from mesh parts and material + * names to material layers. The mesh parts are numbered from "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 +70,23 @@ namespace scriptable { QVector getMaterialNames() { return materialNames; } public slots: + + /**jsdoc + * Makes a copy of the model. + * @function GraphicsModel.cloneModel + * @param {object} [options] - Not used. + * @returns {GraphicsModel} A copy of the model. + */ scriptable::ScriptableModelPointer cloneModel(const QVariantMap& options = QVariantMap()); + + /**jsdoc + * Gets a string description of the model. + * @function GraphicsModel.toString + * @returns {string} A string description of the model. + * @example Report the string description of your avatar's model. + * var model = Graphics.getModel(MyAvatar.sessionUUID); + * print("Avatar model info:", model.toString()); + */ QString toString() const; protected: diff --git a/libraries/graphics/src/graphics/BufferViewHelpers.cpp b/libraries/graphics/src/graphics/BufferViewHelpers.cpp index 301f5d8d73..076cb92dcf 100644 --- a/libraries/graphics/src/graphics/BufferViewHelpers.cpp +++ b/libraries/graphics/src/graphics/BufferViewHelpers.cpp @@ -34,6 +34,50 @@ namespace buffer_helpers { const std::array XYZW = { { "x", "y", "z", "w" } }; const std::array ZERO123 = { { "0", "1", "2", "3" } }; +/**jsdoc + *

The type name of a graphics buffer.

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
ValueDescription
"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 {string} Graphics.BufferTypeName + */ +/**jsdoc + *

The type of a graphics buffer value as accessed by JavaScript.

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
TypeNameDescription
{@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 {Vec3|vec2} Graphics.BufferType + */ QMap ATTRIBUTES{ {"position", gpu::Stream::POSITION }, {"normal", gpu::Stream::NORMAL }, diff --git a/libraries/graphics/src/graphics/Geometry.h b/libraries/graphics/src/graphics/Geometry.h index 20018ba71b..fe1981c0e9 100755 --- a/libraries/graphics/src/graphics/Geometry.h +++ b/libraries/graphics/src/graphics/Geometry.h @@ -79,23 +79,6 @@ public: // Access vertex position value const Vec3& getPos(Index index) const { return _vertexBuffer.get(index); } - /**jsdoc - * - * - * - * - * - * - * - * - * - * - * - * - * - *
ValueDescription
0Points.
1Lines.
2Line strip.
3Triangles.
4Triangle strip.
5Quads.
6Quad strip.
- * @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 + *

The interpretation of mesh elements.

+ * + * + * + * + * + * + * + * + * + * + * + * + * + *
ValueDescription
"points"Points.
"lines"Lines.
"line_strip"Line strip.
"triangles"Triangles.
"triangle_strip"Triangle strip.
"quads"Quads.
"quad_strip"Quad strip.
+ * @typedef {string} Graphics.MeshTopology + */ namespace graphics { DebugEnums TOPOLOGIES{ { Mesh::Topology::POINTS, "points" }, From a92830f2c19b9f73e46121bc2241b156c7e5a3b6 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Mon, 23 Dec 2019 09:09:27 +1300 Subject: [PATCH 18/24] Miscellaneous JSDoc fixes --- .../src/procedural/ProceduralMaterialCache.cpp | 12 ++++++------ .../script-engine/src/AssetScriptingInterface.cpp | 2 +- libraries/shared/src/RegisteredMetaTypes.h | 5 +++-- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/libraries/procedural/src/procedural/ProceduralMaterialCache.cpp b/libraries/procedural/src/procedural/ProceduralMaterialCache.cpp index 8a790cee46..0b64429d15 100644 --- a/libraries/procedural/src/procedural/ProceduralMaterialCache.cpp +++ b/libraries/procedural/src/procedural/ProceduralMaterialCache.cpp @@ -145,7 +145,7 @@ NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMater * "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 *
* Set to "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.
    • *
* Set to "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/shared/src/RegisteredMetaTypes.h b/libraries/shared/src/RegisteredMetaTypes.h index 3b47bb70c6..0a60f2872a 100644 --- a/libraries/shared/src/RegisteredMetaTypes.h +++ b/libraries/shared/src/RegisteredMetaTypes.h @@ -688,6 +688,7 @@ using MeshPointer = std::shared_ptr; /**jsdoc * A handle for a mesh in an entity, such as returned by {@link Entities.getMeshes}. + * * @class MeshProxy * * @hifi-interface @@ -705,14 +706,14 @@ public: virtual MeshPointer getMeshPointer() const = 0; /**jsdoc - * Get the number of vertices in the mesh. + * Gets the number of vertices in the mesh. * @function MeshProxy#getNumVertices * @returns {number} Integer number of vertices in the mesh. */ Q_INVOKABLE virtual int getNumVertices() const = 0; /**jsdoc - * Get the position of a vertex in the mesh. + * Gets the position of a vertex in the mesh. * @function MeshProxy#getPos * @param {number} index - Integer index of the mesh vertex. * @returns {Vec3} Local position of the vertex relative to the mesh. From 61b3b09b23d0065a24ce07a7badc0ed7bc2d996e Mon Sep 17 00:00:00 2001 From: David Rowe Date: Mon, 23 Dec 2019 09:17:08 +1300 Subject: [PATCH 19/24] Fill in some missing summaries. --- .../src/graphics-scripting/GraphicsScriptingUtil.cpp | 12 ++++++------ .../src/graphics-scripting/ScriptableMesh.cpp | 12 ++++++------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingUtil.cpp b/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingUtil.cpp index d1f419728a..92dddc953e 100644 --- a/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingUtil.cpp +++ b/libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingUtil.cpp @@ -59,12 +59,12 @@ QVariant toVariant(const AABox& box) { /**jsdoc * Details of a buffer element's format. * @typedef {object} Graphics.BufferElementFormat - * @property {string} type - * @property {string} semantic - * @property {string} dimension - * @property {number} scalarCount - * @property {number} byteSize - * @property {number} BYTES_PER_ELEMENT + * @property {string} type - Type. + * @property {string} semantic - Semantic. + * @property {string} dimension - Dimension. + * @property {number} scalarCount - Scalar count. + * @property {number} byteSize - Byte size. + * @property {number} BYTES_PER_ELEMENT - Bytes per element. */ QVariant toVariant(const gpu::Element& element) { return QVariantMap{ diff --git a/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.cpp b/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.cpp index 5f81e2daf7..3de5119fa7 100644 --- a/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.cpp +++ b/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.cpp @@ -130,12 +130,12 @@ int scriptable::ScriptableMesh::getSlotNumber(const QString& attributeName) cons /**jsdoc * Details of buffer's format. * @typedef {object} Graphics.BufferFormat - * @property {number} slot - * @property {number} length - * @property {number} byteLength - * @property {number} offset - * @property {number} stride - * @property {Graphics.BufferElementFormat} element + * @property {number} slot - Slot. + * @property {number} length - Length. + * @property {number} byteLength - Byte length. + * @property {number} offset - Offset. + * @property {number} stride - Stride. + * @property {Graphics.BufferElementFormat} element - Element format. */ QVariantMap scriptable::ScriptableMesh::getBufferFormats() const { QVariantMap result; From 7af1845884a3b1999e00449a65322ffc0bf120ab Mon Sep 17 00:00:00 2001 From: David Rowe Date: Mon, 23 Dec 2019 09:20:38 +1300 Subject: [PATCH 20/24] Reinstate mistakenly deleted comment --- .../graphics-scripting/src/graphics-scripting/ScriptableMesh.h | 1 + 1 file changed, 1 insertion(+) diff --git a/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.h b/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.h index 98f496cd9e..f05b32d090 100644 --- a/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.h +++ b/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.h @@ -1,3 +1,4 @@ +// // Copyright 2018 High Fidelity, Inc. // // Distributed under the Apache License, Version 2.0. From f7336d9141c2ed000447c4b5a3d81225475738ba Mon Sep 17 00:00:00 2001 From: David Rowe Date: Mon, 23 Dec 2019 14:12:50 +1300 Subject: [PATCH 21/24] Fix @hideconstructor JSDoc tag hiding classes' properties --- tools/jsdoc/hifi-jsdoc-template/tmpl/container.tmpl | 2 +- tools/jsdoc/hifi-jsdoc-template/tmpl/details.tmpl | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) 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 @@ - +

Description

diff --git a/tools/jsdoc/hifi-jsdoc-template/tmpl/details.tmpl b/tools/jsdoc/hifi-jsdoc-template/tmpl/details.tmpl index afb0e9464c..2fb50322cc 100644 --- a/tools/jsdoc/hifi-jsdoc-template/tmpl/details.tmpl +++ b/tools/jsdoc/hifi-jsdoc-template/tmpl/details.tmpl @@ -19,7 +19,7 @@ if (data.defaultvalue && (data.defaultvaluetype === 'object' || data.defaultvalu

Properties

From 2dd981493efe541445f5dbaa17ec8538e1c81554 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Mon, 23 Dec 2019 14:13:48 +1300 Subject: [PATCH 22/24] Update classes' JSDoc per @hideconstructor --- interface/src/ui/InteractiveWindow.h | 1 + libraries/animation/src/AnimationObject.h | 4 +++- libraries/audio-client/src/AudioIOStats.h | 3 ++- libraries/audio/src/AudioEffectOptions.h | 2 +- libraries/audio/src/Sound.h | 1 + .../controllers/src/controllers/impl/MappingBuilderProxy.h | 1 + .../controllers/src/controllers/impl/RouteBuilderProxy.h | 1 + libraries/networking/src/ResourceCache.h | 1 + libraries/script-engine/src/ScriptsModel.h | 1 - libraries/script-engine/src/WebSocketClass.h | 2 +- libraries/script-engine/src/WebSocketServerClass.h | 2 ++ libraries/script-engine/src/XMLHttpRequestClass.h | 2 ++ libraries/shared/src/RegisteredMetaTypes.h | 2 ++ libraries/ui/src/QmlWebWindowClass.h | 2 ++ libraries/ui/src/QmlWindowClass.h | 2 ++ libraries/ui/src/ui/TabletScriptingInterface.h | 2 ++ 16 files changed, 24 insertions(+), 5 deletions(-) diff --git a/interface/src/ui/InteractiveWindow.h b/interface/src/ui/InteractiveWindow.h index 56060f5c27..1198ce8ee9 100644 --- a/interface/src/ui/InteractiveWindow.h +++ b/interface/src/ui/InteractiveWindow.h @@ -110,6 +110,7 @@ using namespace InteractiveWindowEnums; *

Create using {@link Desktop.createWindow}.

* * @class InteractiveWindow + * @hideconstructor * * @hifi-interface * @hifi-client-entity 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(...).

* * @class AudioEffectOptions * @param {AudioEffectOptions.ReverbOptions} [reverbOptions=null] - Reverberation options. diff --git a/libraries/audio/src/Sound.h b/libraries/audio/src/Sound.h index 62fdb9dcdc..205e1cba33 100644 --- a/libraries/audio/src/Sound.h +++ b/libraries/audio/src/Sound.h @@ -130,6 +130,7 @@ typedef QSharedPointer SharedSoundPointer; * * * @class SoundObject + * @hideconstructor * * @hifi-interface * @hifi-client-entity 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/networking/src/ResourceCache.h b/libraries/networking/src/ResourceCache.h index ddc750664f..35261298b9 100644 --- a/libraries/networking/src/ResourceCache.h +++ b/libraries/networking/src/ResourceCache.h @@ -95,6 +95,7 @@ class ScriptableResource : public QObject { * {@link ModelCache.prefetch}, {@link SoundCache.prefetch}, or {@link TextureCache.prefetch}. * * @class ResourceObject + * @hideconstructor * * @hifi-interface * @hifi-client-entity diff --git a/libraries/script-engine/src/ScriptsModel.h b/libraries/script-engine/src/ScriptsModel.h index bd6c9687c1..0412bbf0fe 100644 --- a/libraries/script-engine/src/ScriptsModel.h +++ b/libraries/script-engine/src/ScriptsModel.h @@ -87,7 +87,6 @@ public: * * * @class ScriptsModel - * @hideconstructor * * @hifi-interface diff --git a/libraries/script-engine/src/WebSocketClass.h b/libraries/script-engine/src/WebSocketClass.h index c181965bf7..543f6146a6 100644 --- a/libraries/script-engine/src/WebSocketClass.h +++ b/libraries/script-engine/src/WebSocketClass.h @@ -21,7 +21,7 @@ * near-complete implementation of the WebSocket API described in the Mozilla docs: * https://developer.mozilla.org/en-US/docs/Web/API/WebSocket. * - *

Constructed 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.

diff --git a/libraries/script-engine/src/WebSocketServerClass.h b/libraries/script-engine/src/WebSocketServerClass.h index dfd277fec1..fff33d5bfb 100644 --- a/libraries/script-engine/src/WebSocketServerClass.h +++ b/libraries/script-engine/src/WebSocketServerClass.h @@ -20,6 +20,8 @@ /**jsdoc * Manages {@link WebSocket}s in server entity and assignment client scripts. * + *

Create using new WebSocketServer(...).

+ * * @class WebSocketServer * * @hifi-server-entity diff --git a/libraries/script-engine/src/XMLHttpRequestClass.h b/libraries/script-engine/src/XMLHttpRequestClass.h index cb86cafb67..3ab7d38dda 100644 --- a/libraries/script-engine/src/XMLHttpRequestClass.h +++ b/libraries/script-engine/src/XMLHttpRequestClass.h @@ -61,6 +61,8 @@ XMlHttpRequest.getResponseHeader(QString) function * the Mozilla docs: * https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest. * + *

Create using new XMLHttpRequest(...).

+ * * @class XMLHttpRequest * * @hifi-interface diff --git a/libraries/shared/src/RegisteredMetaTypes.h b/libraries/shared/src/RegisteredMetaTypes.h index 3b47bb70c6..c4a724c13a 100644 --- a/libraries/shared/src/RegisteredMetaTypes.h +++ b/libraries/shared/src/RegisteredMetaTypes.h @@ -688,7 +688,9 @@ using MeshPointer = std::shared_ptr; /**jsdoc * A handle for a mesh in an entity, such as returned by {@link Entities.getMeshes}. + * * @class MeshProxy + * @hideconstructor * * @hifi-interface * @hifi-client-entity diff --git a/libraries/ui/src/QmlWebWindowClass.h b/libraries/ui/src/QmlWebWindowClass.h index 3ca6418195..2c1a5eabbb 100644 --- a/libraries/ui/src/QmlWebWindowClass.h +++ b/libraries/ui/src/QmlWebWindowClass.h @@ -14,6 +14,8 @@ /**jsdoc * A OverlayWebWindow displays an HTML window inside Interface. * + *

Create using new OverlayWebWindow(...).

+ * * @class OverlayWebWindow * @param {string|OverlayWindow.Properties} [titleOrProperties="WebWindow"] - The window's title or initial property values. * @param {string} [source="about:blank"] - The URL of the HTML to display. Not used unless the first parameter is the window diff --git a/libraries/ui/src/QmlWindowClass.h b/libraries/ui/src/QmlWindowClass.h index ef9d1a8771..3a2f202bd3 100644 --- a/libraries/ui/src/QmlWindowClass.h +++ b/libraries/ui/src/QmlWindowClass.h @@ -26,6 +26,8 @@ class QScriptContext; * control is defined by a "WebView.qml" file included in the Interface install.) Alternatively, an {@link OverlayWebWindow} * can be used for HTML-based windows.

* + *

Create using new OverlayWindow(...).

+ * * @class OverlayWindow * @param {string|OverlayWindow.Properties} [titleOrProperties="WebWindow"] - The window's title or initial property values. * @param {string} [source] - The source of the QML to display. Not used unless the first parameter is the window title. diff --git a/libraries/ui/src/ui/TabletScriptingInterface.h b/libraries/ui/src/ui/TabletScriptingInterface.h index 04222b3ea1..c063307597 100644 --- a/libraries/ui/src/ui/TabletScriptingInterface.h +++ b/libraries/ui/src/ui/TabletScriptingInterface.h @@ -217,6 +217,7 @@ Q_DECLARE_METATYPE(TabletButtonsProxyModel*); *

Retrieve an existing tablet or create a new tablet using {@link Tablet.getTablet}.

* * @class TabletProxy + * @hideconstructor * * @hifi-interface * @hifi-client-entity @@ -586,6 +587,7 @@ Q_DECLARE_METATYPE(TabletProxy*); *

Create a new button using {@link TabletProxy#addButton}.

* * @class TabletButtonProxy + * @hideconstructor * * @hifi-interface * @hifi-client-entity From 67bfe03724f21c2118eaf8ad4a2155f87bdbd257 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Mon, 23 Dec 2019 14:27:34 +1300 Subject: [PATCH 23/24] Use the @hideconstructor tag in anticipation of it working --- .../graphics-scripting/src/graphics-scripting/ScriptableMesh.h | 1 + .../src/graphics-scripting/ScriptableMeshPart.h | 1 + .../graphics-scripting/src/graphics-scripting/ScriptableModel.h | 1 + 3 files changed, 3 insertions(+) diff --git a/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.h b/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.h index f05b32d090..8d70eda9e4 100644 --- a/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.h +++ b/libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.h @@ -34,6 +34,7 @@ namespace scriptable { *

Created using the {@link Graphics} API, {@link GraphicsModel.cloneModel}, or {@link GraphicsMesh.cloneMesh}.

* * @class GraphicsMesh + * @hideconstructor * * @hifi-interface * @hifi-client-entity diff --git a/libraries/graphics-scripting/src/graphics-scripting/ScriptableMeshPart.h b/libraries/graphics-scripting/src/graphics-scripting/ScriptableMeshPart.h index 00645145c5..78ddb4f2b0 100644 --- a/libraries/graphics-scripting/src/graphics-scripting/ScriptableMeshPart.h +++ b/libraries/graphics-scripting/src/graphics-scripting/ScriptableMeshPart.h @@ -17,6 +17,7 @@ namespace scriptable { * {@link GraphicsMeshPart.cloneMeshPart}.

* * @class GraphicsMeshPart + * @hideconstructor * * @hifi-interface * @hifi-client-entity diff --git a/libraries/graphics-scripting/src/graphics-scripting/ScriptableModel.h b/libraries/graphics-scripting/src/graphics-scripting/ScriptableModel.h index faa65f8bf6..6dc2a06747 100644 --- a/libraries/graphics-scripting/src/graphics-scripting/ScriptableModel.h +++ b/libraries/graphics-scripting/src/graphics-scripting/ScriptableModel.h @@ -25,6 +25,7 @@ namespace scriptable { *

Created using the {@link Graphics} API or {@link GraphicsModel.cloneModel}.

* * @class GraphicsModel + * @hideconstructor * * @hifi-interface * @hifi-client-entity From 00bd81b8c3bbd4b9720c5e3d1844af1ea7ad0c49 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 24 Dec 2019 09:52:19 +1300 Subject: [PATCH 24/24] using MyAvatar.getTargetAvatar or AvatarList.getAvatar. --- interface/src/avatar/MyAvatar.h | 2 +- .../src/avatars-renderer/Avatar.cpp | 7 + .../src/avatars-renderer/Avatar.h | 9 +- .../src/avatars-renderer/ScriptAvatar.h | 169 ++++++++++++++++ libraries/avatars/src/AvatarHashMap.h | 2 +- libraries/avatars/src/ScriptAvatarData.h | 182 +++++++++++++----- 6 files changed, 314 insertions(+), 57 deletions(-) diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index 7822b6a8f3..9b9bc2d9df 100644 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -1183,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. diff --git a/libraries/avatars-renderer/src/avatars-renderer/Avatar.cpp b/libraries/avatars-renderer/src/avatars-renderer/Avatar.cpp index d0ab314edf..a9e16e9ff1 100644 --- a/libraries/avatars-renderer/src/avatars-renderer/Avatar.cpp +++ b/libraries/avatars-renderer/src/avatars-renderer/Avatar.cpp @@ -1920,6 +1920,13 @@ void Avatar::setParentJointIndex(quint16 parentJointIndex) { } } +/**jsdoc + * Information about a joint in an avatar's skeleton hierarchy. + * @typedef {object} SkeletonJoint + * @property {string} name - Joint name. + * @property {number} index - Joint index. + * @property {number} parentIndex - Index of this joint's parent (-1 if no parent). + */ QList Avatar::getSkeleton() { SkeletonModelPointer skeletonModel = _skeletonModel; if (skeletonModel) { diff --git a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h index e68edb3c9b..dcd4d00db0 100644 --- a/libraries/avatars-renderer/src/avatars-renderer/Avatar.h +++ b/libraries/avatars-renderer/src/avatars-renderer/Avatar.h @@ -480,14 +480,7 @@ public: /**jsdoc * Gets information on all the joints in the avatar's skeleton. * @function MyAvatar.getSkeleton - * @returns {MyAvatar.SkeletonJoint[]} Information about each joint in the avatar's skeleton. - */ - /**jsdoc - * Information about a single joint in an Avatar's skeleton hierarchy. - * @typedef {object} MyAvatar.SkeletonJoint - * @property {string} name - Joint name. - * @property {number} index - Joint index. - * @property {number} parentIndex - Index of this joint's parent (-1 if no parent). + * @returns {SkeletonJoint[]} Information about each joint in the avatar's skeleton. */ Q_INVOKABLE QList getSkeleton(); diff --git a/libraries/avatars-renderer/src/avatars-renderer/ScriptAvatar.h b/libraries/avatars-renderer/src/avatars-renderer/ScriptAvatar.h index 3bc98e72a0..3f8fc4f88b 100644 --- a/libraries/avatars-renderer/src/avatars-renderer/ScriptAvatar.h +++ b/libraries/avatars-renderer/src/avatars-renderer/ScriptAvatar.h @@ -16,6 +16,64 @@ #include "Avatar.h" +/**jsdoc + * Information about an avatar. + * + *

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

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

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

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

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

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

Warning: These coordinates are not necessarily in meters.

+ *

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

+ * @function ScriptAvatar.getDefaultJointTranslation + * @param {number} index - The joint index. + * @returns {Vec3} The default translation of the joint (in model coordinates) if avatar data are available and the joint + * index is valid, otherwise {@link Vec3(0)|Vec3.ZERO}. + */ glm::vec3 getDefaultJointTranslation(int index) const; + + /**jsdoc + * Gets the offset applied to the avatar for rendering. + * @function ScriptAvatar.getSkeletonOffset + * @returns {Vec3} The skeleton offset if avatar data are available, otherwise {@link Vec3(0)|Vec3.ZERO}. + */ glm::vec3 getSkeletonOffset() const; + + /**jsdoc + * Gets the position of a joint in the avatar. + * @function ScriptAvatar.getJointPosition + * @param {number} index - The index of the joint. + * @returns {Vec3} The position of the joint in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't + * available. + */ glm::vec3 getJointPosition(int index) const; + + /**jsdoc + * Gets the position of a joint in the current avatar. + * @function ScriptAvatar.getJointPosition + * @param {string} name - The name of the joint. + * @returns {Vec3} The position of the joint in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't + * available. + */ glm::vec3 getJointPosition(const QString& name) const; + + /**jsdoc + * Gets the position of the current avatar's neck in world coordinates. + * @function ScriptAvatar.getNeckPosition + * @returns {Vec3} The position of the neck in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't + * available. + */ glm::vec3 getNeckPosition() const; + + /**jsdoc + * Gets the current acceleration of the avatar. + * @function ScriptAvatar.getAcceleration + * @returns {Vec3} The current acceleration of the avatar, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't available.. + */ glm::vec3 getAcceleration() const; + + /**jsdoc + * Gets the ID of the entity of avatar that the avatar is parented to. + * @function ScriptAvatar.getParentID + * @returns {Uuid} The ID of the entity or avatar that the avatar is parented to. {@link Uuid(0)|Uuid.NULL} if not parented + * or avatar data aren't available. + */ QUuid getParentID() const; + + /**jsdoc + * Gets the joint of the entity or avatar that the avatar is parented to. + * @function ScriptAvatar.getParentJointIndex + * @returns {number} The joint of the entity or avatar that the avatar is parented to. 65535 or + * -1 if parented to the entity or avatar's position and orientation rather than a joint, or avatar data + * aren't available. + */ quint16 getParentJointIndex() const; + + /**jsdoc + * Gets information on all the joints in the avatar's skeleton. + * @function ScriptAvatar.getSkeleton + * @returns {SkeletonJoint[]} Information about each joint in the avatar's skeleton. + */ QVariantList getSkeleton() const; + + /**jsdoc + * @function ScriptAvatar.getSimulationRate + * @param {AvatarSimulationRate} [rateName=""] - Rate name. + * @returns {number} Simulation rate in Hz, or 0.0 if avatar data aren't available. + * @deprecated This function is deprecated and will be removed. + */ float getSimulationRate(const QString& rateName = QString("")) const; + + /**jsdoc + * Gets the position of the left palm in world coordinates. + * @function ScriptAvatar.getLeftPalmPosition + * @returns {Vec3} The position of the left palm in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't + * available. + */ glm::vec3 getLeftPalmPosition() const; + + /**jsdoc + * Gets the rotation of the left palm in world coordinates. + * @function ScriptAvatar.getLeftPalmRotation + * @returns {Quat} The rotation of the left palm in world coordinates, or {@link Quat(0)|Quat.IDENTITY} if the avatar data + * aren't available. + */ glm::quat getLeftPalmRotation() const; + + /**jsdoc + * Gets the position of the right palm in world coordinates. + * @function ScriptAvatar.getLeftPalmPosition + * @returns {Vec3} The position of the right palm in world coordinates, or {@link Vec3(0)|Vec3.ZERO} if avatar data aren't + * available. + */ glm::vec3 getRightPalmPosition() const; + + /**jsdoc + * Gets the rotation of the right palm in world coordinates. + * @function ScriptAvatar.getLeftPalmRotation + * @returns {Quat} The rotation of the right palm in world coordinates, or {@link Quat(0)|Quat.IDENTITY} if the avatar data + * aren't available. + */ glm::quat getRightPalmRotation() const; private: diff --git a/libraries/avatars/src/AvatarHashMap.h b/libraries/avatars/src/AvatarHashMap.h index c474353451..e12e5b4649 100644 --- a/libraries/avatars/src/AvatarHashMap.h +++ b/libraries/avatars/src/AvatarHashMap.h @@ -111,7 +111,7 @@ public: * Gets information about an avatar. * @function AvatarList.getAvatar * @param {Uuid} avatarID - The ID of the avatar. - * @returns {AvatarData} Information about the avatar. + * @returns {ScriptAvatar} Information about the avatar. */ // Null/Default-constructed QUuids will return MyAvatar Q_INVOKABLE virtual ScriptAvatarData* getAvatar(QUuid avatarID) { return new ScriptAvatarData(getAvatarBySessionID(avatarID)); } diff --git a/libraries/avatars/src/ScriptAvatarData.h b/libraries/avatars/src/ScriptAvatarData.h index 9c5c2c6918..7dcd7cc7e1 100644 --- a/libraries/avatars/src/ScriptAvatarData.h +++ b/libraries/avatars/src/ScriptAvatarData.h @@ -16,53 +16,6 @@ #include "AvatarData.h" -/**jsdoc - * Information about an avatar. - * @typedef {object} AvatarData - * @property {Vec3} position - The avatar's position. - * @property {number} scale - The target scale of the avatar without any restrictions on permissible values imposed by the - * domain. - * @property {Vec3} handPosition - A user-defined hand position, in world coordinates. The position moves with the avatar but - * is otherwise not used or changed by Interface. - * @property {number} bodyPitch - The pitch of the avatar's body, in degrees. - * @property {number} bodyYaw - The yaw of the avatar's body, in degrees. - * @property {number} bodyRoll - The roll of the avatar's body, in degrees. - * @property {Quat} orientation - The orientation of the avatar's body. - * @property {Quat} headOrientation - The orientation of the avatar's head. - * @property {number} headPitch - The pitch of the avatar's head relative to the body, in degrees. - * @property {number} headYaw - The yaw of the avatar's head relative to the body, in degrees. - * @property {number} headRoll - The roll of the avatar's head relative to the body, in degrees. - * - * @property {Vec3} velocity - The linear velocity of the avatar. - * @property {Vec3} angularVelocity - The angular velocity of the avatar. - * - * @property {Uuid} sessionUUID - The avatar's session ID. - * @property {string} displayName - The avatar's display name. - * @property {string} sessionDisplayName - The avatar's display name, sanitized and versioned, as defined by the avatar mixer. - * It is unique among all avatars present in the domain at the time. - * @property {boolean} isReplicated - Deprecated: This property is deprecated and will be - * removed. - * @property {boolean} lookAtSnappingEnabled - true if the avatar's eyes snap to look at another avatar's eyes - * when the other avatar is in the line of sight and also has lookAtSnappingEnabled == true. - * - * @property {string} skeletonModelURL - The avatar's FST file. - * @property {AttachmentData[]} attachmentData - Information on the avatar's attachments. - *

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

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

Warning: These coordinates are not necessarily in meters.

+ *

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

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

Warning: These coordinates are not necessarily in meters.

+ *

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

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

Warning: These coordinates are not necessarily in meters.

+ * @function ScriptAvatar.getJointTranslations + * @returns {Vec3[]} The translations of all joints relative to each's parent, in model coordinates, or [] if + * the avatar data aren't available. The values are in the same order as the array returned by + * {@link ScriptAvatar.getJointNames}. + */ Q_INVOKABLE QVector getJointTranslations() const; + + /**jsdoc + * Checks that the data for a joint are valid. + * @function ScriptAvatar.isJointDataValid + * @param {number} index - The index of the joint. + * @returns {boolean} true if the joint data are valid, false if not or the avatar data aren't + * available. + */ Q_INVOKABLE bool isJointDataValid(const QString& name) const; + + /**jsdoc + * Gets the joint index for a named joint. The joint index value is the position of the joint in the array returned by + * {@linkScriptAvatar.getJointNames}. + * @function ScriptAvatar.getJointIndex + * @param {string} name - The name of the joint. + * @returns {number} The index of the joint if valid and avatar data are available, otherwise -1. + */ Q_INVOKABLE int getJointIndex(const QString& name) const; + + /**jsdoc + * Gets the names of all the joints in the avatar. + * @function ScriptAvatar.getJointNames + * @returns {string[]} The joint names, or [] if the avatar data aren't available. + */ Q_INVOKABLE QStringList getJointNames() const; + + /**jsdoc + * Gets information about the models currently attached to the avatar. + * @function ScriptAvatar.getAttachmentData + * @returns {AttachmentData[]} Information about all models attached to the avatar, or [] if the avatar data + * aren't available. + * @deprecated This function is deprecated and will be removed. Use avatar entities instead. + */ Q_INVOKABLE QVector getAttachmentData() const; #if DEV_BUILD || PR_BUILD @@ -185,13 +232,54 @@ public: bool getHasPriority() const; signals: + + /**jsdoc + * Triggered when the avatar's displayName property value changes. + * @function ScriptAvatar.displayNameChanged + * @returns {Signal} + */ void displayNameChanged(); + + /**jsdoc + * Triggered when the avatar's sessionDisplayName property value changes. + * @function ScriptAvatar.sessionDisplayNameChanged + * @returns {Signal} + */ void sessionDisplayNameChanged(); + + /**jsdoc + * Triggered when the avatar's model (i.e., skeletonModelURL property value) is changed. + * @function ScriptAvatar.skeletonModelURLChanged + * @returns {Signal} + */ void skeletonModelURLChanged(); + + /**jsdoc + * Triggered when the avatar's lookAtSnappingEnabled property value changes. + * @function ScriptAvatar.lookAtSnappingChanged + * @param {boolean} enabled - true if look-at snapping is enabled, false if not. + * @returns {Signal} + */ void lookAtSnappingChanged(bool enabled); public slots: + + /**jsdoc + * Gets the rotation of a joint relative to the avatar. + * @function ScriptAvatar.getAbsoluteJointRotationInObjectFrame + * @param {number} index - The index of the joint. + * @returns {Quat} The rotation of the joint relative to the avatar, or {@link Quat(0)|Quat.IDENTITY} if the avatar data + * aren't available. + */ glm::quat getAbsoluteJointRotationInObjectFrame(int index) const; + + /**jsdoc + * Gets the translation of a joint relative to the avatar. + * @function ScriptAvatar.getAbsoluteJointTranslationInObjectFrame + * @param {number} index - The index of the joint. + * @returns {Vec3} The translation of the joint relative to the avatar, or {@link Vec3(0)|Vec3.ZERO} if the avatar data + * aren't available. + */ glm::vec3 getAbsoluteJointTranslationInObjectFrame(int index) const; protected: