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

Merge pull request #16583 from ctrlaltdavid/api-docs

Browse source 
Combined API docs update
This commit is contained in:
Maia Hansen 2020-01-15 12:25:13 -08:00 committed by GitHub
commit b0e524df57
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
55 changed files with 1474 additions and 383 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
interface/src/Application.cpp
View file

@ -693,10 +693,17 @@ private:
* </thead>
* <tbody>
* <tr><td><code>CameraFirstPerson</code></td><td>number</td><td>number</td><td>The camera is in first-person mode.
* </td></tr>
* <em>Legacy first person camera mode.</em></td></tr>
* <tr><td><code>CameraFirstPersonLookAt</code></td><td>number</td><td>number</td><td>The camera is in first-person mode.
* <em>Default first person camera mode.</em></td></tr>
* <tr><td><code>CameraThirdPerson</code></td><td>number</td><td>number</td><td>The camera is in third-person mode.
* </td></tr>
* <tr><td><code>CameraFSM</code></td><td>number</td><td>number</td><td>The camera is in full screen mirror mode.</td></tr>
* <em>Legacy third person camera mode.</em></td></tr>
* <tr><td><code>CameraLookAt</code></td><td>number</td><td>number</td><td>The camera is in third-person mode.
* <em>Default third person camera mode.</em></td></tr>
* <tr><td><code>CameraFSM</code></td><td>number</td><td>number</td><td>The camera is in full screen mirror mode.
* <em>Legacy "look at myself" behavior.</em></td></tr>
* <tr><td><code>CameraSelfie</code></td><td>number</td><td>number</td><td>The camera is in selfie mode.
* <em>Default "look at myself" camera mode.</em></td></tr>
* <tr><td><code>CameraIndependent</code></td><td>number</td><td>number</td><td>The camera is in independent mode.</td></tr>
* <tr><td><code>CameraEntity</code></td><td>number</td><td>number</td><td>The camera is in entity mode.</td></tr>
* <tr><td><code>InHMD</code></td><td>number</td><td>number</td><td>The user is in HMD mode.</td></tr>

2
interface/src/AvatarBookmarks.cpp
View file

@ -187,7 +187,7 @@ void AvatarBookmarks::updateAvatarEntities(const QVariantList &avatarEntities) {
* @property {number} avatarScale - The target scale of the avatar.
* @property {Array<Object<"properties",Entities.EntityProperties>>} [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.
* <p class="important">Deprecated: Use avatar entities instead.
*/

174
interface/src/avatar/MyAvatar.h
View file

@ -148,21 +148,21 @@ class MyAvatar : public Avatar {
* size in the virtual world. <em>Read-only.</em>
* @property {boolean} hasPriority - <code>true</code> if the avatar is in a "hero" zone, <code>false</code> if it isn't.
* <em>Read-only.</em>
* @property {boolean} hasScriptedBlendshapes=false - <code>true</code> if blend shapes are controlled by scripted actions,
* otherwise <code>false</code>. Set this to <code>true</code> before using the {@link MyAvatar.setBlendshape} method,
* @property {boolean} hasScriptedBlendshapes=false - <code>true</code> if blend shapes are controlled by scripted actions,
* otherwise <code>false</code>. Set this to <code>true</code> before using the {@link MyAvatar.setBlendshape} method,
* and set back to <code>false</code> after you no longer want scripted control over the blend shapes.
* <p><strong>Note:</strong> This property will automatically be set to true if the Controller system has valid facial
* blend shape actions.</p>
* @property {boolean} hasProceduralBlinkFaceMovement=true - <code>true</code> if avatars blink automatically by animating
* facial blend shapes, <code>false</code> if automatic blinking is disabled. Set this property to <code>false</code> if
* you wish to fully control the blink facial blend shapes via the {@link MyAvatar.setBlendshape} method.
* @property {boolean} hasProceduralEyeFaceMovement=true - <code>true</code> if the facial blend shapes for an avatar's eyes
* adjust automatically as the eyes move, <code>false</code> if this automatic movement is disabled. Set this property
* to <code>true</code> to prevent the iris from being obscured by the upper or lower lids. Set this property to
* <code>false</code> if you wish to fully control the eye blend shapes via the {@link MyAvatar.setBlendshape} method.
* @property {boolean} hasAudioEnabledFaceMovement=true - <code>true</code> if the avatar's mouth blend shapes animate
* automatically based on detected microphone input, <code>false</code> if this automatic movement is disabled. Set
* this property to <code>false</code> if you wish to fully control the mouth facial blend shapes via the
* <p><strong>Note:</strong> This property will automatically be set to <code>true</code> if the controller system has
* valid facial blend shape actions.</p>
* @property {boolean} hasProceduralBlinkFaceMovement=true - <code>true</code> if avatars blink automatically by animating
* facial blend shapes, <code>false</code> if automatic blinking is disabled. Set this property to <code>false</code>
* to fully control the blink facial blend shapes via the {@link MyAvatar.setBlendshape} method.
* @property {boolean} hasProceduralEyeFaceMovement=true - <code>true</code> if the facial blend shapes for an avatar's eyes
* adjust automatically as the eyes move, <code>false</code> if this automatic movement is disabled. Set this property
* to <code>true</code> to prevent the iris from being obscured by the upper or lower lids. Set this property to
* <code>false</code> to fully control the eye blend shapes via the {@link MyAvatar.setBlendshape} method.
* @property {boolean} hasAudioEnabledFaceMovement=true - <code>true</code> if the avatar's mouth blend shapes animate
* automatically based on detected microphone input, <code>false</code> if this automatic movement is disabled. Set
* this property to <code>false</code> to fully control the mouth facial blend shapes via the
* {@link MyAvatar.setBlendshape} method.
*
* @comment IMPORTANT: This group of properties is copied from Avatar.h; they should NOT be edited here.
@ -286,9 +286,9 @@ class MyAvatar : public Avatar {
* @property {number} isInSittingState - <code>true</code> if the user wearing the HMD is determined to be sitting
* (avatar leaning is disabled, recentering is enabled), <code>false</code> if the user wearing the HMD is
* determined to be standing (avatar leaning is enabled, and avatar recenters if it leans too far).
* If <code>userRecenterModel == 2</code> (i.e., auto) the property value automatically updates as the user sits
* If <code>userRecenterModel == 2</code> (i.e., "auto") the property value automatically updates as the user sits
* or stands, unless <code>isSitStandStateLocked == true</code>. 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
* <code>isSitStandStateLocked == true</code>.
* @property {boolean} isSitStandStateLocked - <code>true</code> to lock the avatar sitting/standing state, i.e., use this
* to disable automatically changing state.
@ -321,10 +321,7 @@ class MyAvatar : public Avatar {
* @borrows Avatar.setAttachmentsVariant as setAttachmentsVariant
* @borrows Avatar.updateAvatarEntity as updateAvatarEntity
* @borrows Avatar.clearAvatarEntity as clearAvatarEntity
* @borrows Avatar.hasScriptedBlendshapes as hasScriptedBlendshapes
* @borrows Avatar.hasProceduralBlinkFaceMovement as hasProceduralBlinkFaceMovement
* @borrows Avatar.hasProceduralEyeFaceMovement as hasProceduralEyeFaceMovement
* @borrows Avatar.hasAudioEnabledFaceMovement as hasAudioEnabledFaceMovement
* @borrows Avatar.setForceFaceTrackerConnected as setForceFaceTrackerConnected
* @borrows Avatar.setSkeletonModelURL as setSkeletonModelURL
* @borrows Avatar.getAttachmentData as getAttachmentData
* @borrows Avatar.setAttachmentData as setAttachmentData
@ -530,7 +527,7 @@ public:
* <tr><td><code>0</code></td><td>ForceSit</td><td>Assumes 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).</td></tr>
* <tr><td><code>1</code></td><td>ForceStand</td><td>Assumes 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).</td></tr>
* <tr><td><code>2</code></td><td>Auto</td><td>Interface detects when the user is standing or seated in the real world.
* Avatar leaning is disabled when the user is sitting (i.e., avatar always recenters), and avatar leaning is enabled
@ -657,7 +654,7 @@ public:
* <p>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
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards">Avatar Standards</a>.</p>
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards.html">Avatar Standards</a>.</p>
* @function MyAvatar.overrideAnimation
* @param {string} url - The URL to the animation file. Animation files may be in glTF or FBX format, but only need to
* contain the avatar skeleton and animation data. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs
@ -765,7 +762,7 @@ public:
* <p>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
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards">Avatar Standards</a>.
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards.html">Avatar Standards</a>.
* @function MyAvatar.overrideRoleAnimation
* @param {string} role - The animation role to override
* @param {string} url - The URL to the animation file. Animation files need to be in glTF or FBX format, but only need to
@ -1186,7 +1183,7 @@ public:
/**jsdoc
* Gets information on the avatar your avatar is currently looking at.
* @function MyAvatar.getTargetAvatar
* @returns {AvatarData} Information on the avatar being looked at.
* @returns {ScriptAvatar} Information on the avatar being looked at, <code>null</code> if no avatar is being looked at.
*/
// FIXME: The return type doesn't have a conversion to a script value so the function always returns undefined in
// JavaScript. Note: When fixed, JSDoc is needed for the return type.
@ -1795,56 +1792,57 @@ public:
void prepareAvatarEntityDataForReload();
/**jsdoc
* Turns the avatar's head until it faces the target point within a +90/-90 degree range.
* Once this method is called, API calls will have full control of the head for a limited time.
* If this method is not called for two seconds, the engine will regain control of the head.
* @function MyAvatar.setHeadLookAt
* @param {Vec3} lookAtTarget - The target point in world coordinates.
*/
* Turns the avatar's head until it faces the target point within a +90/-90 degree range.
* Once this method is called, API calls will have full control of the head for a limited time.
* If this method is not called for 2 seconds, the engine will regain control of the head.
* @function MyAvatar.setHeadLookAt
* @param {Vec3} lookAtTarget - The target point in world coordinates.
*/
Q_INVOKABLE void setHeadLookAt(const glm::vec3& lookAtTarget);
/**jsdoc
* Returns the current target point of the head's look direction in world coordinates.
* @function MyAvatar.getHeadLookAt
* @returns {Vec3} The head's "look at" target in world coordinates.
*/
* Returns the current target point of the head's look direction in world coordinates.
* @function MyAvatar.getHeadLookAt
* @returns {Vec3} The head's look-at target in world coordinates.
*/
Q_INVOKABLE glm::vec3 getHeadLookAt() { return _lookAtCameraTarget; }
/**jsdoc
* Returns control of the avatar's head to the engine, and releases control from API calls.
* @function MyAvatar.releaseHeadLookAtControl
*/
* Returns control of the avatar's head to the engine, and releases control from API calls.
* @function MyAvatar.releaseHeadLookAtControl
*/
Q_INVOKABLE void releaseHeadLookAtControl();
/**jsdoc
* Forces the avatar's eyes to look at a specified location. Once this method is called, API calls
* have full control of the eyes for a limited time. If this method is not called for two seconds,
* the engine regains control of the eyes.
* @function MyAvatar.setEyesLookAt
* @param {Vec3} lookAtTarget - The target point in world coordinates.
*/
* Forces the avatar's eyes to look at a specified location. Once this method is called, API calls
* have full control of the eyes for a limited time. If this method is not called for two seconds,
* the engine regains control of the eyes.
* @function MyAvatar.setEyesLookAt
* @param {Vec3} lookAtTarget - The target point in world coordinates.
*/
Q_INVOKABLE void setEyesLookAt(const glm::vec3& lookAtTarget);
/**jsdoc
* Returns the current target point of the eyes look direction in world coordinates.
* @function MyAvatar.getEyesLookAt
* @returns {Vec3} The eyes' "look at" target in world coordinates.
*/
* Returns the current target point of the eyes look direction in world coordinates.
* @function MyAvatar.getEyesLookAt
* @returns {Vec3} The eyes' look-at target in world coordinates.
*/
Q_INVOKABLE glm::vec3 getEyesLookAt() { return _eyesLookAtTarget.get(); }
/**jsdoc
* Returns control of the avatar's eyes to the engine, and releases control from API calls.
* @function MyAvatar.releaseEyesLookAtControl
*/
* Returns control of the avatar's eyes to the engine, and releases control from API calls.
* @function MyAvatar.releaseEyesLookAtControl
*/
Q_INVOKABLE void releaseEyesLookAtControl();
/**jsdoc
* Aims the pointing directional blending towards the provided target point. The "point" reaction should be triggered
* before using this method with the code <code>MyAvatar.beginReaction("point")</code>.
* @function MyAvatar.setPointAt
* @param {Vec3} pointAtTarget - The target point in world coordinates.
* @returns {boolean} <code>true</code> if the target point lays in front of the avatar, <code>false</code> if it doesn't.
*/
* Sets the point-at target for the <code>"point"</code> reaction that may be started with {@link MyAvatar.beginReaction}.
* The point-at target is set only if it is in front of the avatar.
* <p>Note: The <code>"point"</code> reaction should be started before calling this method.</p>
* @function MyAvatar.setPointAt
* @param {Vec3} pointAtTarget - The target to point at, in world coordinates.
* @returns {boolean} <code>true</code> if the target point was set, <code>false</code> if it wasn't.
*/
Q_INVOKABLE bool setPointAt(const glm::vec3& pointAtTarget);
glm::quat getLookAtRotation() { return _lookAtYaw * _lookAtPitch; }
@ -1928,7 +1926,7 @@ public:
* @param {boolean} isActive - <code>true</code> if flow simulation is enabled on the joint, <code>false</code> if it isn't.
* @param {boolean} isCollidable - <code>true</code> to enable collisions in the flow simulation, <code>false</code> to
* disable.
* @param {Object<JointName, MyAvatar.FlowPhysicsOptions>} [physicsConfig>] - Physics configurations for particular entity
* @param {Object<JointName, MyAvatar.FlowPhysicsOptions>} [physicsConfig] - Physics configurations for particular entity
* and avatar joints.
* @param {Object<JointName, MyAvatar.FlowCollisionsOptions>} [collisionsConfig] - Collision configurations for particular
* entity and avatar joints.
@ -1952,8 +1950,8 @@ public:
/**jsdoc
* Starts a sitting action for the avatar.
* @function MyAvatar.beginSit
* @param {Vec3} position - The point in space where the avatar will sit.
* @param {Quat} rotation - Initial absolute orientation of the avatar once is seated.
* @param {Vec3} position - The position where the avatar should sit.
* @param {Quat} rotation - The initial orientation of the seated avatar.
*/
Q_INVOKABLE void beginSit(const glm::vec3& position, const glm::quat& rotation);
@ -1961,15 +1959,14 @@ public:
* Ends a sitting action for the avatar.
* @function MyAvatar.endSit
* @param {Vec3} position - The position of the avatar when standing up.
* @param {Quat} rotation - The absolute rotation of the avatar once the sitting action ends.
* @param {Quat} rotation - The orientation of the avatar when standing up.
*/
Q_INVOKABLE void endSit(const glm::vec3& position, const glm::quat& rotation);
/**jsdoc
* Gets whether the avatar is in a seated pose. The seated pose is set by calling the
* MyAvatar::beginSit method.
* Gets whether the avatar is in a seated pose. The seated pose is set by calling {@link MyAvatar.beginSit}.
* @function MyAvatar.isSeated
* @returns {boolean} <code>true</code> if the avatar is in a seated pose.
* @returns {boolean} <code>true</code> if the avatar is in a seated pose, <code>false</code> if it isn't.
*/
Q_INVOKABLE bool isSeated() { return _characterController.getSeated(); }
@ -2072,8 +2069,8 @@ public slots:
* @param {boolean} [hasOrientation=false] - Set to <code>true</code> to set the orientation of the avatar.
* @param {Quat} [orientation=Quat.IDENTITY] - The new orientation for the avatar.
* @param {boolean} [shouldFaceLocation=false] - Set to <code>true</code> to position the avatar a short distance away from
* @param {boolean} [withSafeLanding=true] - Set to <code>false</code> 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 <code>false</code> to disable safe landing when teleporting.
*/
void goToLocation(const glm::vec3& newPosition,
bool hasOrientation = false, const glm::quat& newOrientation = glm::quat(),
@ -2348,43 +2345,52 @@ public slots:
virtual void setModelScale(float scale) override;
/**jsdoc
* MyAvatar.getTriggerReactions
* Returns a list of reactions names that can be triggered using MyAvatar.triggerReaction().
* @returns {string[]} Array of reaction names.
* Gets the list of reactions names that can be triggered using {@link MyAvatar.triggerReaction}.
* <p>See also: {@link MyAvatar.getBeginEndReactions}.
* @function MyAvatar.getTriggerReactions
* @returns {string[]} List of reaction names that can be triggered using {@link MyAvatar.triggerReaction}.
* @example <caption>List the available trigger reactions.</caption>
* 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}.
* <p>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 <caption>List the available begin-end reactions.</caption>
* 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.
* <p>Only reaction names returned by {@link MyAvatar.getTriggerReactions} are available.</p>
* @function MyAvatar.triggerReaction
* @param {string} reactionName - The reaction to trigger.
* @returns {boolean} <code>true</code> if the reaction was played, <code>false</code> 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.
* <p>Only reactions returned by {@link MyAvatar.getBeginEndReactions} are available.</p>
* @function MyAvatar.beginReaction
* @param {string} reactionName - The reaction to start playing.
* @returns {boolean} <code>true</code> if the reaction was started, <code>false</code> 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} <code>true</code> if the reaction was stopped, <code>false</code> if the reaction is not supported.
*/
bool endReaction(QString reactionName);

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

@ -52,8 +52,9 @@
* <em>Read-only.</em>
* <p><strong>Warning:</strong> Not yet implemented.</p>
*
* @property {FilterFlags} PICK_BYPASS_IGNORE - Allows pick to intersect entities even when their ignorePickIntersection property is 'true'.
* For debug purposes. <em>Read-only.</em>
* @property {FilterFlags} PICK_BYPASS_IGNORE - Allows pick to intersect entities even when their
* <code>ignorePickIntersection</code> property value is <code>true</code>. For debug purposes.
* <em>Read-only.</em>
*
* @property {IntersectionType} INTERSECTED_NONE - Intersected nothing. <em>Read-only.</em>
* @property {IntersectionType} INTERSECTED_ENTITY - Intersected an entity. <em>Read-only.</em>

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

@ -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 <code>type</code>.
*/
Q_INVOKABLE QVariantMap getPointerScriptParameters(unsigned int uid) const;

46
interface/src/scripting/DesktopScriptingInterface.cpp
View file

@ -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
* <p>A docking location of an <code>InteractiveWindow</code>.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Name</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>0</code></td><td>TOP</td><td>Dock to the top edge of the Interface window.</td></tr>
* <tr><td><code>1</code></td><td>BOTTOM</td><td>Dock to the bottom edge of the Interface window.</td></tr>
* <tr><td><code>2</code></td><td>LEFT</td><td>Dock to the left edge of the Interface window.</td></tr>
* <tr><td><code>3</code></td><td>RIGHT</td><td>Dock to the right edge of the Interface window.</td></tr>
* <tbody>
* </table>
* @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 <code>InteractiveWindow</code>. Used when defining the `relativePosition` property of an `InteractiveWindow`.
* The possible relative position anchors of an <code>InteractiveWindow</code> 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
* <p>A display mode for an <code>InteractiveWindow</code>.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Name</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>0</code></td><td>VIRTUAL</td><td>The window is displayed inside Interface: in the desktop window in
* desktop mode or on the HUD surface in HMD mode.</td></tr>
* <tr><td><code>1</code></td><td>NATIVE</td><td>The window is displayed separately from the Interface window, as its
* own separate window.</td></tr>
* <tbody>
* </table>
* @typedef {number} InteractiveWindow.PresentationMode
*/
QVariantMap DesktopScriptingInterface::getPresentationMode() {
static QVariantMap presentationModes {
{ "VIRTUAL", Virtual },

6
interface/src/scripting/DesktopScriptingInterface.h
View file

@ -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.
* <em>Read-only.</em>
* @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.
* <em>Read-only.</em>
*/
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 <code>WebView</code>
* control (defined by "WebView.qml" included in the Interface install) to embed an HTML web page (complete with
* <code>EventBridge</code> object).
* @param {InteractiveWindow.Properties} [properties] - Initial window properties.
* @param {InteractiveWindow.WindowProperties} [properties] - Initial window properties.
* @returns {InteractiveWindow} A new window object.
* @example <caption>Open a dialog in its own window separate from Interface.</caption>
* var nativeWindow = Desktop.createWindow(Script.resourcesPath() + 'qml/OverlayWindowTest.qml', {

6
interface/src/scripting/WindowScriptingInterface.h
View file

@ -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 - <code>true</code> if the Interface window is minimized, <code>false</code> if it isn't.
* @returns {Signal}
* @example <caption>Report the "minimized" state of the Interface window when it changes.</caption>
* function onWindowMinimizedChanged(minimized) {
* print("Window minimized: " + minimized);
* }
*
* Window.minimizedChanged.connect(onWindowMinimizedChanged);
*/

39
interface/src/ui/InteractiveWindow.cpp
View file

@ -129,8 +129,8 @@ void InteractiveWindow::emitMainWindowResizeEvent() {
}
/**jsdoc
* A set of properties used when creating an <code>InteractiveWindow</code>.
* @typedef {object} InteractiveWindow.Properties
* Property values used when creating an <code>InteractiveWindow</code>.
* @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 <code>NATIVE</code> 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
* <code>relativePosition</code>, if used.
* @property {Vec2} [relativePosition] - The position of the window, relative to the <code>relativePositionAnchor</code>, in
* pixels. Excludes the window frame.
* @property {boolean} [isFullScreenWindow] - <code>true</code> to make the window full screen.
*/
/**jsdoc
* <p>A set of flags customizing <code>InteractiveWindow</code> controls. The value is constructed by using the <code>|</code>
* (bitwise OR) operator on the individual flag values.</code>.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Name</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>0x00000001</code></td><td>Window</td><td>Displays the window as a window rather than a dialog.</td></tr>
* <tr><td><code>0x00001000</code></td><td>WindowTitleHint</td><td>Adds a title bar.</td><td>
* <tr><td><code>0x00002000</code></td><td>WindowSystemMenuHint</td><td>Adds a window system menu.</td><td>
* <tr><td><code>0x00004000</code></td><td>WindowMinimizeButtonHint</td><td>Adds a minimize button.</td><td>
* <tr><td><code>0x00008000</code></td><td>WindowMaximizeButtonHint</td><td>Adds a maximize button.</td><td>
* <tr><td><code>0x00040000</code></td><td>WindowStaysOnTopHint</td><td>The window stays on top of other windows.
* <em>Not used on Windows.</em>
* <tr><td><code>0x08000000</code></td><td>WindowCloseButtonHint</td><td>Adds a close button.</td><td>
* <tbody>
* </table>
* @typedef {number} InteractiveWindow.OverrideFlags
*/
// OverrideFlags is per InteractiveWindow.qml.
InteractiveWindow::InteractiveWindow(const QString& sourceUrl, const QVariantMap& properties, bool restricted) {
InteractiveWindowPresentationMode presentationMode = InteractiveWindowPresentationMode::Native;

55
interface/src/ui/InteractiveWindow.h
View file

@ -76,12 +76,42 @@ namespace InteractiveWindowEnums {
};
Q_ENUM_NS(InteractiveWindowFlags);
/**jsdoc
* <p>A display mode for an <code>InteractiveWindow</code>.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Name</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>0</code></td><td>VIRTUAL</td><td>The window is displayed inside Interface: in the desktop window in
* desktop mode or on the HUD surface in HMD mode.</td></tr>
* <tr><td><code>1</code></td><td>NATIVE</td><td>The window is displayed separately from the Interface window, as its
* own separate window.</td></tr>
* <tbody>
* </table>
* @typedef {number} InteractiveWindow.PresentationMode
*/
enum InteractiveWindowPresentationMode {
Virtual,
Native
};
Q_ENUM_NS(InteractiveWindowPresentationMode);
/**jsdoc
* <p>A docking location of an <code>InteractiveWindow</code>.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Name</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>0</code></td><td>TOP</td><td>Dock to the top edge of the Interface window.</td></tr>
* <tr><td><code>1</code></td><td>BOTTOM</td><td>Dock to the bottom edge of the Interface window.</td></tr>
* <tr><td><code>2</code></td><td>LEFT</td><td>Dock to the left edge of the Interface window.</td></tr>
* <tr><td><code>3</code></td><td>RIGHT</td><td>Dock to the right edge of the Interface window.</td></tr>
* <tbody>
* </table>
* @typedef {number} InteractiveWindow.DockArea
*/
enum DockArea {
TOP,
BOTTOM,
@ -90,6 +120,24 @@ namespace InteractiveWindowEnums {
};
Q_ENUM_NS(DockArea);
/**jsdoc
* <p>The anchor for a relative position of an <code>InteractiveWindow</code>.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Name</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>0</code></td><td>NO_ANCHOR</td><td>Position is not relative to any part of the Interface window.</td></tr>
* <tr><td><code>1</code></td><td>TOP_LEFT</td><td>Position is offset from the top left of the Interface window.</td></tr>
* <tr><td><code>2</code></td><td>TOP_RIGHT</td><td>Position is offset from the top right of the Interface window.</td></tr>
* <tr><td><code>3</code></td><td>BOTTOM_RIGHT</td><td>Position offset from the bottom right of the Interface
* window.</td></tr>
* <tr><td><code>4</code></td><td>BOTTOM_LEFFT</td><td>Position is offset from the bottom left of the Interface
* window.</td></tr>
* <tbody>
* </table>
* @typedef {number} InteractiveWindow.RelativePositionAnchor
*/
enum RelativePositionAnchor {
NO_ANCHOR,
TOP_LEFT,
@ -110,13 +158,18 @@ using namespace InteractiveWindowEnums;
* <p>Create using {@link Desktop.createWindow}.</p>
*
* @class InteractiveWindow
* @hideconstructor
*
* @hifi-interface
* @hifi-client-entity
* @hifi-avatar
*
* @property {string} title - The title of the window.
* @property {Vec2} position - The position of the window, in pixels.
* @property {Vec2} position - The absolute position of the window, in pixels.
* @property {InteractiveWindow.RelativePositionAnchor} relativePositionAnchor - The anchor for the
* <code>relativePosition</code>, if used.
* @property {Vec2} relativePosition - The position of the window, relative to the <code>relativePositionAnchor</code>, in
* pixels. Excludes the window frame.
* @property {Vec2} size - The size of the window, in pixels.
* @property {boolean} visible - <code>true</code> if the window is visible, <code>false</code> if it isn't.
* @property {InteractiveWindow.PresentationMode} presentationMode - The presentation mode of the window:

4
libraries/animation/src/AnimationObject.h
View file

@ -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

3
libraries/audio-client/src/AudioIOStats.h
View file

@ -42,9 +42,10 @@ class AudioStreamStatsInterface : public QObject {
/**jsdoc
* Statistics for an audio stream.
*
* <p>Provided in the {@link AudioStats} API.</p>
* <p>Provided in properties of the {@link AudioStats} API.</p>
*
* @class AudioStats.AudioStreamStats
* @hideconstructor
*
* @hifi-interface
* @hifi-client-entity

2
libraries/audio/src/AudioEffectOptions.h
View file

@ -18,7 +18,7 @@
/**jsdoc
* Audio effect options used by the {@link Audio} API.
*
* <p>Create using <code>new AudioEffectOptions(reverbOptions)</code>.</p>
* <p>Create using <code>new AudioEffectOptions(...)</code>.</p>
*
* @class AudioEffectOptions
* @param {AudioEffectOptions.ReverbOptions} [reverbOptions=null] - Reverberation options.

1
libraries/audio/src/Sound.h
View file

@ -130,6 +130,7 @@ typedef QSharedPointer<Sound> SharedSoundPointer;
* </ul>
*
* @class SoundObject
* @hideconstructor
*
* @hifi-interface
* @hifi-client-entity

7
libraries/avatars-renderer/src/avatars-renderer/Avatar.cpp
View file

@ -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<QVariant> Avatar::getSkeleton() {
SkeletonModelPointer skeletonModel = _skeletonModel;
if (skeletonModel) {

13
libraries/avatars-renderer/src/avatars-renderer/Avatar.h
View file

@ -207,7 +207,7 @@ public:
/**jsdoc
* Gets the default rotation of a joint (in the current avatar) relative to its parent.
* <p>For information on the joint hierarchy used, see
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards">Avatar Standards</a>.</p>
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards.html">Avatar Standards</a>.</p>
* @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.
* <p><strong>Warning:</strong> These coordinates are not necessarily in meters.</p>
* <p>For information on the joint hierarchy used, see
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards">Avatar Standards</a>.</p>
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards.html">Avatar Standards</a>.</p>
* @function MyAvatar.getDefaultJointTranslation
* @param {number} index - The joint index.
* @returns {Vec3} The default translation of the joint (in model coordinates) if the joint index is valid, otherwise
@ -480,14 +480,7 @@ public:
/**jsdoc
* Gets information on all the joints in the avatar's skeleton.
* @function MyAvatar.getSkeleton
* @returns {MyAvatar.SkeletonJoint[]} Information about each joint in the avatar's skeleton.
*/
/**jsdoc
* Information about a single joint in an Avatar's skeleton hierarchy.
* @typedef {object} MyAvatar.SkeletonJoint
* @property {string} name - Joint name.
* @property {number} index - Joint index.
* @property {number} parentIndex - Index of this joint's parent (-1 if no parent).
* @returns {SkeletonJoint[]} Information about each joint in the avatar's skeleton.
*/
Q_INVOKABLE QList<QVariant> getSkeleton();

169
libraries/avatars-renderer/src/avatars-renderer/ScriptAvatar.h
View file

@ -16,6 +16,64 @@
#include "Avatar.h"
/**jsdoc
* Information about an avatar.
*
* <p>Created using {@link MyAvatar.getTargetAvatar} or {@link AvatarList.getAvatar}.</p>
*
* @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 - <span class="important">Deprecated: This property is deprecated and will be
* removed.</span>
* @property {boolean} lookAtSnappingEnabled - <code>true</code> 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 <code>lookAtSnappingEnabled == true</code>.
*
* @property {string} skeletonModelURL - The avatar's FST file.
* @property {AttachmentData[]} attachmentData - Information on the avatar's attachments.
* <p class="important">Deprecated: This property is deprecated and will be removed. Use avatar entities instead.</p>
* @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.
* <p>For information on the joint hierarchy used, see
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards.html">Avatar Standards</a>.</p>
* @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.
* <p><strong>Warning:</strong> These coordinates are not necessarily in meters.</p>
* <p>For information on the joint hierarchy used, see
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards.html">Avatar Standards</a>.</p>
* @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. <code>65535</code> or
* <code>-1</code> 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 <code>0.0</code> 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:

39
libraries/avatars/src/AvatarData.h
View file

@ -533,21 +533,21 @@ class AvatarData : public QObject, public SpatiallyNestable {
* @property {boolean} hasPriority - <code>true</code> if the avatar is in a "hero" zone, <code>false</code> if it isn't.
* <em>Read-only.</em>
* @property {boolean} hasScriptedBlendshapes=false - <code>true</code> if blend shapes are controlled by scripted actions,
* otherwise <code>false</code>. Set this to <code>true</code> before using the {@link MyAvatar.setBlendshape} method,
* otherwise <code>false</code>. Set this to <code>true</code> before using the {@link Avatar.setBlendshape} method,
* and set back to <code>false</code> after you no longer want scripted control over the blend shapes.
* <p><strong>Note:</strong> This property will automatically be set to true if the Controller system has valid facial
* blend shape actions.</p>
* <p><strong>Note:</strong> This property will automatically be set to <code>true</code> if the controller system has
* valid facial blend shape actions.</p>
* @property {boolean} hasProceduralBlinkFaceMovement=true - <code>true</code> if avatars blink automatically by animating
* facial blend shapes, <code>false</code> if automatic blinking is disabled. Set this property to <code>false</code> if
* you wish to fully control the blink facial blend shapes via the {@link MyAvatar.setBlendshape} method.
* facial blend shapes, <code>false</code> if automatic blinking is disabled. Set this property to <code>false</code>
* to fully control the blink facial blend shapes via the {@link Avatar.setBlendshape} method.
* @property {boolean} hasProceduralEyeFaceMovement=true - <code>true</code> if the facial blend shapes for an avatar's eyes
* adjust automatically as the eyes move, <code>false</code> if this automatic movement is disabled. Set this property
* to <code>true</code> to prevent the iris from being obscured by the upper or lower lids. Set this property to
* <code>false</code> if you wish to fully control the eye blend shapes via the {@link MyAvatar.setBlendshape} method.
* <code>false</code> to fully control the eye blend shapes via the {@link Avatar.setBlendshape} method.
* @property {boolean} hasAudioEnabledFaceMovement=true - <code>true</code> if the avatar's mouth blend shapes animate
* automatically based on detected microphone input, <code>false</code> if this automatic movement is disabled. Set
* this property to <code>false</code> if you wish to fully control the mouth facial blend shapes via the
* {@link MyAvatar.setBlendshape} method.
* this property to <code>false</code> to fully control the mouth facial blend shapes via the
* {@link Avatar.setBlendshape} method.
*/
Q_PROPERTY(glm::vec3 position READ getWorldPosition WRITE setPositionViaScript)
Q_PROPERTY(float scale READ getDomainLimitedScale WRITE setTargetScale)
@ -860,7 +860,7 @@ public:
/**jsdoc
* Gets the rotation of a joint relative to its parent. For information on the joint hierarchy used, see
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards">Avatar Standards</a>.
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards.html">Avatar Standards</a>.
* @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.
* <p><strong>Warning:</strong> These coordinates are not necessarily in meters.</p>
* <p>For information on the joint hierarchy used, see
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards">Avatar Standards</a>.</p>
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards.html">Avatar Standards</a>.</p>
* @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
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards">Avatar Standards</a>.
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards.html">Avatar Standards</a>.
* @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.
* <p><strong>Warning:</strong> These coordinates are not necessarily in meters.</p>
* <p>For information on the joint hierarchy used, see
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards">Avatar Standards</a>.</p>
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards.html">Avatar Standards</a>.</p>
* @function Avatar.getJointTranslation
* @param {number} name - The name of the joint.
* @returns {Vec3} The translation of the joint relative to its parent, in model coordinates.
@ -1134,8 +1134,8 @@ public:
/**jsdoc
* Sets the value of a blend shape to animate your avatar's face. In order for other users to see the resulting animations
* on your avatar's face, set {@link Avatar.hasScriptedBlendshapes} to <code>true</code>. When you are done using this API,
* set {@link Avatar.hasScriptedBlendshapes} back to <code>false</code> when the animation is complete.
* on your avatar's face, set <code>hasScriptedBlendshapes</code> to <code>true</code>. When you are done using this API,
* set <code>hasScriptedBlendshapes</code> back to <code>false</code> when the animation is complete.
* @function Avatar.setBlendshape
* @param {string} name - The name of the blendshape, per the
* {@link https://docs.highfidelity.com/create/avatars/avatar-standards.html#blendshapes Avatar Standards}.
@ -1174,7 +1174,7 @@ public:
/**jsdoc
* @function Avatar.updateAvatarEntity
* @param {Uuid} entityID - The entity ID.
* @param {Array.<byte>} entityData - Entity data.
* @param {ArrayBuffer} entityData - Entity data.
* @deprecated This function is deprecated and will be removed.
*/
Q_INVOKABLE virtual void updateAvatarEntity(const QUuid& entityID, const QByteArray& entityData);
@ -1188,12 +1188,12 @@ public:
Q_INVOKABLE virtual void clearAvatarEntity(const QUuid& entityID, bool requiresRemovalFromTree = true);
/**jsdoc
* <p class="important">Deprecated: This method is deprecated and will be removed.</p>
* 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.
* <p class="important">Deprecated: This method is deprecated and will be removed. Use the
* <code>Avatar.hasScriptedBlendshapes</code> or <code>MyAvatar.hasScriptedBlendshapes</code> property instead.</p>
* @function Avatar.setForceFaceTrackerConnected
* @param {boolean} connected - <code>true</code> to enable blendshape changes to be transmitted to other users,
* @param {boolean} connected - <code>true</code> to enable blend shape changes to be transmitted to other users,
* <code>false</code> to disable.
*/
Q_INVOKABLE void setForceFaceTrackerConnected(bool connected) { setHasScriptedBlendshapes(connected); }
@ -1964,6 +1964,7 @@ Q_DECLARE_METATYPE(RayToAvatarIntersectionResult)
QScriptValue RayToAvatarIntersectionResultToScriptValue(QScriptEngine* engine, const RayToAvatarIntersectionResult& results);
void RayToAvatarIntersectionResultFromScriptValue(const QScriptValue& object, RayToAvatarIntersectionResult& results);
// No JSDoc because it's not provided as a type to the script engine.
class ParabolaToAvatarIntersectionResult {
public:
bool intersects { false };

2
libraries/avatars/src/AvatarHashMap.h
View file

@ -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)); }

182
libraries/avatars/src/ScriptAvatarData.h
View file

@ -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 - <span class="important">Deprecated: This property is deprecated and will be
* removed.</span>
* @property {boolean} lookAtSnappingEnabled - <code>true</code> 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 <code>lookAtSnappingEnabled == true</code>.
*
* @property {string} skeletonModelURL - The avatar's FST file.
* @property {AttachmentData[]} attachmentData - Information on the avatar's attachments.
* <p class="important">Deprecated: This property is deprecated and will be removed. Use avatar entities instead.</p>
* @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 - <code>true</code> if the avatar is in a "hero" zone, <code>false</code> 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 <code>-1</code> 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
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards.html">Avatar Standards</a>.
* @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.
* <p><strong>Warning:</strong> These coordinates are not necessarily in meters.</p>
* <p>For information on the joint hierarchy used, see
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards.html">Avatar Standards</a>.</p>
* @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
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards.html">Avatar Standards</a>.
* @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.
* <p><strong>Warning:</strong> These coordinates are not necessarily in meters.</p>
* <p>For information on the joint hierarchy used, see
* <a href="https://docs.highfidelity.com/create/avatars/avatar-standards.html">Avatar Standards</a>.</p>
* @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 <code>[]</code> 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<glm::quat> 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.
* <p><strong>Warning:</strong> These coordinates are not necessarily in meters.</p>
* @function ScriptAvatar.getJointTranslations
* @returns {Vec3[]} The translations of all joints relative to each's parent, in model coordinates, or <code>[]</code> 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<glm::vec3> 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} <code>true</code> if the joint data are valid, <code>false</code> 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 <code>-1</code>.
*/
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 <code>[]</code> 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 <code>[]</code> if the avatar data
* aren't available.
* @deprecated This function is deprecated and will be removed. Use avatar entities instead.
*/
Q_INVOKABLE QVector<AttachmentData> getAttachmentData() const;
#if DEV_BUILD || PR_BUILD
@ -185,13 +232,54 @@ public:
bool getHasPriority() const;
signals:
/**jsdoc
* Triggered when the avatar's <code>displayName</code> property value changes.
* @function ScriptAvatar.displayNameChanged
* @returns {Signal}
*/
void displayNameChanged();
/**jsdoc
* Triggered when the avatar's <code>sessionDisplayName</code> property value changes.
* @function ScriptAvatar.sessionDisplayNameChanged
* @returns {Signal}
*/
void sessionDisplayNameChanged();
/**jsdoc
* Triggered when the avatar's model (i.e., <code>skeletonModelURL</code> property value) is changed.
* @function ScriptAvatar.skeletonModelURLChanged
* @returns {Signal}
*/
void skeletonModelURLChanged();
/**jsdoc
* Triggered when the avatar's <code>lookAtSnappingEnabled</code> property value changes.
* @function ScriptAvatar.lookAtSnappingChanged
* @param {boolean} enabled - <code>true</code> if look-at snapping is enabled, <code>false</code> 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:

2
libraries/controllers/src/controllers/ScriptingInterface.h
View file

@ -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 <code>true</code> then the mapping is enabled, otherwise it is disabled.
* @param {boolean} [enable=true] - If <code>true</code> then the mapping is enabled, otherwise it is disabled.
*/
Q_INVOKABLE void enableMapping(const QString& mappingName, bool enable = true);

1
libraries/controllers/src/controllers/impl/MappingBuilderProxy.h
View file

@ -54,6 +54,7 @@ class UserInputMapper;
* </ul>
*
* @class MappingObject
* @hideconstructor
*
* @hifi-interface
* @hifi-client-entity

1
libraries/controllers/src/controllers/impl/RouteBuilderProxy.h
View file

@ -36,6 +36,7 @@ class ScriptingInterface;
* types.<p>
*
* @class RouteObject
* @hideconstructor
*
* @hifi-interface
* @hifi-client-entity

6
libraries/entities/src/EntityScriptingInterface.h
View file

@ -1867,7 +1867,8 @@ public slots:
* @function Entities.getMeshes
* @param {Uuid} entityID - The ID of the <code>Model</code> or <code>PolyVox</code> 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:
* <code>Model</code> or <code>PolyVox</code> entity; otherwise <code>undefined</code>.
* @param {boolean} success - <code>true</code> if the {@link Entities.getMeshes} call was successful, <code>false</code>
* 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);

60
libraries/graphics-scripting/src/graphics-scripting/Forward.h
View file

@ -36,39 +36,6 @@ namespace scriptable {
using ModelProviderPointer = std::shared_ptr<scriptable::ModelProvider>;
using WeakModelProviderPointer = std::weak_ptr<scriptable::ModelProvider>;
/**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; }
};

129
libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingInterface.cpp
View file

@ -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. <em>Currently only triangles is supported.</em>
* @property {number[]} indices - Vertex indices to use for the mesh faces, in tuples per the <code>topology</code>.
* @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: <code>"hifi_pbr"</code> and <code>"hifi_shader_simple"</code>.
* @property {Vec3|string} [albedo] - The albedo color. Component values are in the range <code>0.0</code> &ndash;
* <code>1.0</code>.
* If <code>"fallthrough"</code> then it falls through to the material below.
* @property {number|string} [opacity] - The opacity, range <code>0.0</code> &ndash; <code>1.0</code>.
* If <code>"fallthrough"</code> then it falls through to the material below.
*
* @property {number|string} [opacityCutoff] - The opacity cutoff threshold used to determine the opaque texels of the
* <code>opacityMap</code> when <code>opacityMapMode</code> is <code>"OPACITY_MAP_MASK"</code>. Range <code>0.0</code>
* &ndash; <code>1.0</code>.
* If <code>"fallthrough"</code> then it falls through to the material below.
* <code>"hifi_pbr"</code> model only.
* @property {number|string} [roughness] - The roughness, range <code>0.0</code> &ndash; <code>1.0</code>.
* If <code>"fallthrough"</code> then it falls through to the material below.
* <code>"hifi_pbr"</code> model only.
* @property {number|string} [metallic] - The metallicness, range <code>0.0</code> &ndash; <code>1.0</code>.
* If <code>"fallthrough"</code> then it falls through to the material below.
* <code>"hifi_pbr"</code> model only.
* @property {number|string} [scattering] - The scattering, range <code>0.0</code> &ndash; <code>1.0</code>.
* If <code>"fallthrough"</code> then it falls through to the material below.
* <code>"hifi_pbr"</code> model only.
* @property {boolean|string} [unlit] - <code>true</code> if the material is unaffected by lighting, <code>false</code> if it
* it is lit by the key light and local lights.
* If <code>"fallthrough"</code> then it falls through to the material below.
* <code>"hifi_pbr"</code> model only.
* @property {Vec3|string} [emissive] - The emissive color, i.e., the color that the material emits. Component values are
* in the range <code>0.0</code> &ndash; <code>1.0</code>.
* If <code>"fallthrough"</code> then it falls through to the material below.
* <code>"hifi_pbr"</code> model only.
* @property {string} [albedoMap] - The URL of the albedo texture image.
* If <code>"fallthrough"</code> then it falls through to the material below.
* <code>"hifi_pbr"</code> model only.
* @property {string} [opacityMap] - The URL of the opacity texture image.
* <code>"hifi_pbr"</code> model only.
* @property {string} [opacityMapMode] - The mode defining the interpretation of the opacity map. Values can be:
* <ul>
* <li><code>"OPACITY_MAP_OPAQUE"</code> for ignoring the opacity map information.</li>
* <li><code>"OPACITY_MAP_MASK"</code> for using the <code>opacityMap</code> as a mask, where only the texel greater
* than <code>opacityCutoff</code> are visible and rendered opaque.</li>
* <li><code>"OPACITY_MAP_BLEND"</code> for using the <code>opacityMap</code> for alpha blending the material surface
* with the background.</li>
* </ul>
* If <code>"fallthrough"</code> then it falls through to the material below.
* <code>"hifi_pbr"</code> model only.
* @property {string} [occlusionMap] - The URL of the occlusion texture image.
* If <code>"fallthrough"</code> then it falls through to the material below.
* <code>"hifi_pbr"</code> model only.
* @property {string} [lightMap] - The URL of the light map texture image.
* If <code>"fallthrough"</code> then it falls through to the material below.
* <code>"hifi_pbr"</code> model only.
* @property {string} [lightmapParams] - Parameters for controlling how <code>lightMap</code> is used.
* If <code>"fallthrough"</code> then it falls through to the material below.
* <code>"hifi_pbr"</code> model only.
* <p><em>Currently not used.</em></p>
* @property {string} [scatteringMap] - The URL of the scattering texture image.
* If <code>"fallthrough"</code> then it falls through to the material below.
* <code>"hifi_pbr"</code> model only.
* @property {string} [emissiveMap] - The URL of the emissive texture image.
* If <code>"fallthrough"</code> then it falls through to the material below.
* <code>"hifi_pbr"</code> model only.
* @property {string} [metallicMap] - The URL of the metallic texture image.
* If <code>"fallthrough"</code> then it and <code>specularMap</code> fall through to the material below.
* Only use one of <code>metallicMap</code> and <code>specularMap</code>.
* <code>"hifi_pbr"</code> model only.
* @property {string} [specularMap] - The URL of the specular texture image.
* Only use one of <code>metallicMap</code> and <code>specularMap</code>.
* <code>"hifi_pbr"</code> model only.
* @property {string} [roughnessMap] - The URL of the roughness texture image.
* If <code>"fallthrough"</code> then it and <code>glossMap</code> fall through to the material below.
* Only use one of <code>roughnessMap</code> and <code>glossMap</code>.
* <code>"hifi_pbr"</code> model only.
* @property {string} [glossMap] - The URL of the gloss texture image.
* Only use one of <code>roughnessMap</code> and <code>glossMap</code>.
* <code>"hifi_pbr"</code> model only.
* @property {string} [normalMa]p - The URL of the normal texture image.
* If <code>"fallthrough"</code> then it and <code>bumpMap</code> fall through to the material below.
* Only use one of <code>normalMap</code> and <code>bumpMap</code>.
* <code>"hifi_pbr"</code> model only.
* @property {string} [bumpMap] - The URL of the bump texture image.
* Only use one of <code>normalMap</code> and <code>bumpMap</code>.
* <code>"hifi_pbr"</code> model only.
* @property {string} [materialParams] - Parameters for controlling the material projection and repetition.
* If <code>"fallthrough"</code> then it falls through to the material below.
* <code>"hifi_pbr"</code> model only.
* <p><em>Currently not used.</em></p>
* @property {string} [cullFaceMode="CULL_BACK"] - Specifies Which faces of the geometry to render. Values can be:
* <ul>
* <li><code>"CULL_NONE"</code> to render both sides of the geometry.</li>
* <li><code>"CULL_FRONT"</code> to cull the front faces of the geometry.</li>
* <li><code>"CULL_BACK"</code> (the default) to cull the back faces of the geometry.</li>
* </ul>
* If <code>"fallthrough"</code> then it falls through to the material below.
* <code>"hifi_pbr"</code> model only.
* @property {Mat4|string} [texCoordTransform0] - The transform to use for all of the maps apart from
* <code>occlusionMap</code> and <code>lightMap</code>.
* If <code>"fallthrough"</code> then it falls through to the material below.
* <code>"hifi_pbr"</code> model only.
* @property {Mat4|string} [texCoordTransform1] - The transform to use for <code>occlusionMap</code> and
* <code>lightMap</code>.
* If <code>"fallthrough"</code> then it falls through to the material below.
* <code>"hifi_pbr"</code> model only.
*
* @property {string} procedural - The definition of a procedural shader material.
* <code>"hifi_shader_simple"</code> model only.
* <p><em>Currently not used.</em></p>
*
* @property {boolean} defaultFallthrough - <code>true</code> if all properties fall through to the material below unless
* they are set, <code>false</code> 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);

84
libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingInterface.h
View file

@ -23,7 +23,10 @@
/**jsdoc
* The experimental Graphics API <em>(experimental)</em> lets you query and manage certain graphics-related structures (like underlying meshes and textures) from scripting.
* The <code>Graphics</code> 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.
* <p>Note: The model data may be used for more than one instance of the item displayed in the scene.</p>
* @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 <caption>Report some details of your avatar's model.</caption>
* 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} <code>true</code> if the update was completed successfully, <code>false</code> 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,
* <code>"Model"</code> entities and <code>"model"</code> 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] - <em>Not used.</em>
* @param {number} [partNumber=-1] - <em>Not used.</em>
* @returns {boolean} <code>true</code> if the model can be updated, <code>false</code> if it can't.
* @example <caption>Test whether different types of items can be updated.</caption>
* 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:

18
libraries/graphics-scripting/src/graphics-scripting/GraphicsScriptingUtil.cpp
View file

@ -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 - 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{
{ "type", gpu::toString(element.getType()) },

28
libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.cpp
View file

@ -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 - 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;
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<Graphics.BufferTypeName, Graphics.BufferType>} 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 <code>false</code> to not update the particular vertex.
* @callback GraphicsMesh~updateVertexAttributesCallback
* @param {Object<Graphics.BufferTypeName, Graphics.BufferType>} 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<Graphics.BufferTypeName, Graphics.BufferType>|boolean} The attribute values to update the vertex with, or
* <code>false</code> to not update the vertex.
*/
glm::uint32 scriptable::ScriptableMesh::updateVertexAttributes(QScriptValue _callback) {
auto mesh = getMeshPointer();
if (!mesh) {

173
libraries/graphics-scripting/src/graphics-scripting/ScriptableMesh.h
View file

@ -29,17 +29,41 @@
namespace scriptable {
/**jsdoc
* @typedef {object} Graphics.Mesh
* @property {Graphics.MeshPart[]} parts - Array of submesh part references.
* @property {string[]} attributeNames - Vertex attribute names (color, normal, etc.)
* @property {number} numParts - The number of parts contained in the mesh.
* @property {number} numIndices - Total number of vertex indices in the mesh.
* @property {number} numVertices - Total number of vertices in the Mesh.
* @property {number} numAttributes - Number of currently defined vertex attributes.
* @property {boolean} valid
* @property {boolean} strong
* @property {object} extents
* @property {object} bufferFormats
* A handle to in-memory mesh data in a {@link GraphicsModel}.
*
* <p>Created using the {@link Graphics} API, {@link GraphicsModel.cloneModel}, or {@link GraphicsMesh.cloneMesh}.</p>
*
* @class GraphicsMesh
* @hideconstructor
*
* @hifi-interface
* @hifi-client-entity
* @hifi-avatar
*
* @property {number} numParts - The number of mesh parts.
* <em>Read-only.</em>
* @property {GraphicsMeshPart[]} parts - The mesh parts.
* <em>Read-only.</em>
* @property {number} numIndices - The total number of vertex indices in the mesh.
* <em>Read-only.</em>
* @property {number} numVertices - The total number of vertices in the mesh.
* <em>Read-only.</em>
* @property {number} numAttributes - The number of vertex attributes.
* <em>Read-only.</em>
* @property {Graphics.BufferTypeName[]} attributeNames - The names of the vertex attributes.
* <em>Read-only.</em>
* @property {boolean} valid - <code>true</code> if the mesh is valid, <code>false</code> if it isn't.
* <em>Read-only.</em>
* @property {boolean} strong - <code>true</code> if the mesh is valid and able to be used, <code>false</code> if it isn't.
* <em>Read-only.</em>
* @property {Graphics.MeshExtents} extents - The mesh extents, in model coordinates.
* <em>Read-only.</em>
* @property {Object<Graphics.BufferTypeName, Graphics.BufferFormat>} bufferFormats - Details of the buffers used for the
* mesh.
* <em>Read-only.</em>
*
* @borrows GraphicsMesh.getVertextAttributes as getVertextAttributes
* @borrows GraphicsMesh.setVertextAttributes as setVertextAttributes
*/
class ScriptableMesh : public ScriptableMeshBase, QScriptable {
Q_OBJECT
@ -82,26 +106,153 @@ namespace scriptable {
int getSlotNumber(const QString& attributeName) const;
public slots:
/**jsdoc
* Gets the model the mesh is part of.
* <p><em>Currently doesn't work.</em></p>
* @function GraphicsMesh.getParentModel
* @returns {GraphicsModel} The model the mesh is part of, <code>null</code> if it isn't part of a model.
*/
const scriptable::ScriptableModelPointer getParentModel() const { return qobject_cast<scriptable::ScriptableModel*>(model); }
/**jsdoc
* Gets the vertex indices.
* @function GraphicsMesh.getIndices
* @returns {number[]} The vertex indices.
*/
QVector<glm::uint32> 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
* <code>origin</code> it is considered to be "nearby".
* @returns {number[]} The indices of nearby vertices.
*/
QVector<glm::uint32> 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, <code>0</code> if the <code>name</code> 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} <code>1</code> if the attribute name was valid and the attribute values were set, <code>0</code>
* otherwise.
*/
glm::uint32 fillAttribute(const QString& attributeName, const QVariant& value);
/**jsdoc
* Removes an attribute from all vertices.
* <p>Note: The <code>"position"</code> attribute cannot be removed.</p>
* @function GraphicsMesh.removeAttribute
* @param {Graphics.BufferTypeName} name - The name of the attribute to remove.
* @returns {boolean} <code>true</code> if the attribute existed and was removed, <code>false</code> 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 <code>name</code> 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<Graphics.BufferTypeName,Graphics.BufferType>} The attribute names and values for the vertex.
* @throws Throws an error if the <code>index</code> 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<Graphics.BufferTypeNAme,Graphics.BufferType>} values - The attribute names and values. Need not
* specify unchanged values.
* @returns {boolean} <code>true</code> if the index and the attribute names and values were valid and the vertex was
* updated, <code>false</code> otherwise.
* @throws Throws an error if the <code>index</code> 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 <code>index</code> is invalid or <code>name</code> 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} <code>true</code> if the vertex attribute value was set, <code>false</code> if it wasn't.
* @throws Throws an error if the <code>index</code> is invalid or <code>name</code> 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} <code>true</code> if the index is valid and that vertex has the attribute if specified.
* @throws Throws an error if the <code>index</code> if invalid or <code>name</code> 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;
};

245
libraries/graphics-scripting/src/graphics-scripting/ScriptableMeshPart.h
View file

@ -11,23 +11,50 @@
namespace scriptable {
/**jsdoc
* @typedef {object} Graphics.MeshPart
* @property {boolean} valid
* @property {number} partIndex - The part index (within the containing Mesh).
* @property {number} firstVertexIndex
* @property {number} baseVertexIndex
* @property {number} lastVertexIndex
* @property {Graphics.Topology} topology - element interpretation (currently only 'triangles' is supported).
* @property {string[]} attributeNames - Vertex attribute names (color, normal, etc.)
* @property {number} numIndices - Number of vertex indices that this mesh part refers to.
* @property {number} numVerticesPerFace - Number of vertices per face (eg: 3 when topology is 'triangles').
* @property {number} numFaces - Number of faces represented by the mesh part (numIndices / numVerticesPerFace).
* @property {number} numVertices - Total number of vertices in the containing Mesh.
* @property {number} numAttributes - Number of currently defined vertex attributes.
* @property {object} extents
* @property {object} bufferFormats
*/
* A handle to in-memory mesh part data in a {@link GraphicsModel}.
*
* <p>Created using the {@link Graphics} API, {@link GraphicsModel.cloneModel}, {@link GraphicsMesh.cloneMesh}, or
* {@link GraphicsMeshPart.cloneMeshPart}.</p>
*
* @class GraphicsMeshPart
* @hideconstructor
*
* @hifi-interface
* @hifi-client-entity
* @hifi-avatar
*
* @property {boolean} valid - <code>true</code> if the mesh part is valid, <code>false</code> if it isn't.
* <em>Read-only.</em>
* @property {number} partIndex - The index of the part within the <em>whole</em> mesh (i.e., parent and mesh parts).
* <em>Read-only.</em>
* @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. <em>Currently only triangles is supported.</em>
* @property {number} numIndices - The number of vertex indices in the mesh part.
* @property {number} numVertices - The number of vertices in the <em>whole</em> mesh (i.e., parent and mesh parts).
* <em>Read-only.</em>
* @property {number} numVerticesPerFace - The number of vertices per face, per the <code>topology</code> (e.g., 3 for
* triangles).
* <em>Read-only.</em>
* @property {number} numFaces - The number of faces represented by the mesh part.
* <em>Read-only.</em>
* @property {number} numAttributes - The number of vertex attributes in the <em>whole</em> mesh (i.e., parent and mesh
* parts).
* <em>Read-only.</em>
* @property {Graphics.BufferTypeName[]} attributeNames - The names of the vertex attributes in the <em>whole</em> mesh
* (i.e., parent and mesh parts).
* <em>Read-only.</em>
* @property {Graphics.MeshExtents} extents - The mesh part extents, in model coordinates.
* <em>Read-only.</em>
* @property {Object<Graphics.BufferTypeName, Graphics.BufferFormat>} bufferFormats - Details of the buffers used for the
* <em>whole</em> mesh (i.e., parent and mesh parts).
* <em>Read-only.</em>
* @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 +82,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<glm::uint32> getIndices() const;
/**jsdoc
* Sets the vertex indices.
* @function GraphicsMeshPart.setIndices
* @param {number[]} indices - The vertex indices.
* @returns {boolean} <code>true</code> if successful, <code>false</code> if not.
* @throws Throws an error if the number of indices isn't the same, or an index is invalid.
*/
bool setIndices(const QVector<glm::uint32>& 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
* <code>origin</code> it is considered to be "nearby".
* @returns {number[]} The indices of nearby vertices.
*/
QVector<glm::uint32> findNearbyPartVertexIndices(const glm::vec3& origin, float epsilon = 1e-6) const;
/**jsdoc
* Gets the value of an attribute for all vertices in the <em>whole</em> 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 <code>name</code> 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 <code>index</code> is invalid or <code>name</code> 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} <code>true</code> if the vertex attribute value was set, <code>false</code> if it wasn't.
* @throws Throws an error if the <code>index</code> is invalid or <code>name</code> 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 <code>topology</code>.
*/
QVector<glm::uint32> 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.
* <p><strong>Warning:</strong> Currently doesn't work as expected.</p>
* @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.
* <p><strong>Warning:</strong> Currently doesn't work as expected.</p>
* @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 <em>whole</em> 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} <code>1</code> if the attribute name was valid and the attribute values were set, <code>0</code>
* otherwise.
*/
glm::uint32 fillAttribute(const QString& attributeName, const QVariant& value);
/**jsdoc
* Removes an attribute from all vertices in the <em>whole</em> mesh (i.e., parent and mesh parts).
* <p>Note: The <code>"position"</code> attribute cannot be removed.</p>
* @function GraphicsMeshPArt.removeAttribute
* @param {Graphics.BufferTypeName} name - The name of the attribute to remove.
* @returns {boolean} <code>true</code> if the attribute existed and was removed, <code>false</code> 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} <code>true</code> if the deduplication succeeded, <code>false</code> 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} <code>true</code> if the mesh part was successfully replaced, <code>false</code> if it wasn't.
*/
bool replaceMeshPartData(scriptable::ScriptableMeshPartPointer source, const QVector<QString>& attributeNames = QVector<QString>());
/**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 <em>whole</em> 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 <em>whole</em> 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} <code>true</code> if the index is valid and that vertex has the attribute if specified.
* @throws Throws an error if the <code>index</code> if invalid or <code>name</code> 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;

52
libraries/graphics-scripting/src/graphics-scripting/ScriptableModel.h
View file

@ -17,14 +17,36 @@ namespace scriptable {
using ScriptableMeshes = QVector<scriptable::ScriptableMeshPointer>;
/**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.<string,Graphics.MaterialLayer[]>} 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.
* <p>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.</p>
*
* <p>Created using the {@link Graphics} API or {@link GraphicsModel.cloneModel}.</p>
*
* @class GraphicsModel
* @hideconstructor
*
* @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; <code>null</code>
* if the model is not associated with an entity or avatar.
* <em>Read-only.</em>
* @property {number} numMeshes - The number of meshes contained in the model.
* <em>Read-only.</em>
* @property {GraphicsMesh[]} meshes - The meshes in the model. Each mesh may have more than one mesh part.
* <em>Read-only.</em>
* @property {string[]} materialNames - The names of the materials used by each mesh part in the model. The names are in
* the order of the <code>meshes</code> and their mesh parts.
* <em>Read-only.</em>
* @property {Object.<string,Graphics.MaterialLayer[]>} materialLayers - The mapping from mesh parts and material
* names to material layers. The mesh parts are numbered from <code>"0"</code> per the array indexes of
* <code>materialNames</code>. The material names are those used in <code>materialNames</code>. (You can look up a
* material layer by mesh part number or by material name.)
* <em>Read-only.</em>
*/
class ScriptableModel : public ScriptableModelBase {
Q_OBJECT
Q_PROPERTY(QUuid objectID MEMBER objectID CONSTANT)
@ -49,7 +71,23 @@ namespace scriptable {
QVector<QString> getMaterialNames() { return materialNames; }
public slots:
/**jsdoc
* Makes a copy of the model.
* @function GraphicsModel.cloneModel
* @param {object} [options] - <em>Not used.</em>
* @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 <caption>Report the string description of your avatar's model.</caption>
* var model = Graphics.getModel(MyAvatar.sessionUUID);
* print("Avatar model info:", model.toString());
*/
QString toString() const;
protected:

44
libraries/graphics/src/graphics/BufferViewHelpers.cpp
View file

@ -34,6 +34,50 @@ namespace buffer_helpers {
const std::array<const char*, 4> XYZW = { { "x", "y", "z", "w" } };
const std::array<const char*, 4> ZERO123 = { { "0", "1", "2", "3" } };
/**jsdoc
* <p>The type name of a graphics buffer.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>"position"</code></td><td>Position buffer.</td></tr>
* <tr><td><code>"normal"</code></td><td>normal buffer.</td></tr>
* <tr><td><code>"tangent"</code></td><td>Tangent buffer.</td></tr>
* <tr><td><code>"color"</code></td><td>Color buffer.</td></tr>
* <tr><td><code>"skin_cluster_index"</code></td><td>Skin cluster index buffer.</td></tr>
* <tr><td><code>"skin_cluster_weight"</code></td><td>Skin cluster weight buffer.</td></tr>
* <tr><td><code>"texcoord0"</code></td><td>First UV coordinates buffer.</td></tr>
* <tr><td><code>"texcoord1"</code></td><td>Second UV coordinates buffer.</td></tr>
* <tr><td><code>"texcoord2"</code></td><td>Third UV coordinates buffer.</td></tr>
* <tr><td><code>"texcoord3"</code></td><td>Fourth UV coordinates buffer.</td></tr>
* <tr><td><code>"texcoord4"</code></td><td>Fifth UV coordinates buffer.</td></tr>
* </tbody>
* </table>
* @typedef {string} Graphics.BufferTypeName
*/
/**jsdoc
* <p>The type of a graphics buffer value as accessed by JavaScript.</p>
* <table>
* <thead>
* <tr><th>Type</th><th>Name</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td>{@link Vec3}</td><td><code>"position"</code></td><td>Position buffer.</td></tr>
* <tr><td>{@link Vec3}</td><td><code>"normal"</code></td><td>normal buffer.</td></tr>
* <tr><td>{@link Vec3}</td><td><code>"tangent"</code></td><td>Tangent buffer.</td></tr>
* <tr><td>{@link Vec4}</td><td><code>"color"</code></td><td>Color buffer.</td></tr>
* <tr><td>{@link Vec4}</td><td><code>"skin_cluster_index"</code></td><td>Skin cluster index buffer.</td></tr>
* <tr><td>{@link Vec4}</td><td><code>"skin_cluster_weight"</code></td><td>Skin cluster weight buffer.</td></tr>
* <tr><td>{@link Vec2}</td><td><code>"texcoord0"</code></td><td>First UV coordinates buffer.</td></tr>
* <tr><td>{@link Vec2}</td><td><code>"texcoord1"</code></td><td>Second UV coordinates buffer.</td></tr>
* <tr><td>{@link Vec2}</td><td><code>"texcoord2"</code></td><td>Third UV coordinates buffer.</td></tr>
* <tr><td>{@link Vec2}</td><td><code>"texcoord3"</code></td><td>Fourth UV coordinates buffer.</td></tr>
* <tr><td>{@link Vec2}</td><td><code>"texcoord4"</code></td><td>Fifth UV coordinates buffer.</td></tr>
* </tbody>
* </table>
* @typedef {Vec3|vec2} Graphics.BufferType
*/
QMap<QString,int> ATTRIBUTES{
{"position", gpu::Stream::POSITION },
{"normal", gpu::Stream::NORMAL },

17
libraries/graphics/src/graphics/Geometry.h
View file

@ -79,23 +79,6 @@ public:
// Access vertex position value
const Vec3& getPos(Index index) const { return _vertexBuffer.get<Vec3>(index); }
/**jsdoc
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>0</code></td><td>Points.</td></tr>
* <tr><td><code>1</code></td><td>Lines.</td></tr>
* <tr><td><code>2</code></td><td>Line strip.</td></tr>
* <tr><td><code>3</code></td><td>Triangles.</td></tr>
* <tr><td><code>4</code></td><td>Triangle strip.</td></tr>
* <tr><td><code>5</code></td><td>Quads.</td></tr>
* <tr><td><code>6</code></td><td>Quad strip.</td></tr>
* </tbody>
* </table>
* @typedef {number} Graphics.Topology
*/
enum Topology {
POINTS = 0,
LINES,

18
libraries/graphics/src/graphics/GpuHelpers.cpp
View file

@ -8,6 +8,24 @@
#include "GpuHelpers.h"
/**jsdoc
* <p>The interpretation of mesh elements.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>"points"</code></td><td>Points.</td></tr>
* <tr><td><code>"lines"</code></td><td>Lines.</td></tr>
* <tr><td><code>"line_strip"</code></td><td>Line strip.</td></tr>
* <tr><td><code>"triangles"</code></td><td>Triangles.</td></tr>
* <tr><td><code>"triangle_strip"</code></td><td>Triangle strip.</td></tr>
* <tr><td><code>"quads"</code></td><td>Quads.</td></tr>
* <tr><td><code>"quad_strip"</code></td><td>Quad strip.</td></tr>
* </tbody>
* </table>
* @typedef {string} Graphics.MeshTopology
*/
namespace graphics {
DebugEnums<Mesh::Topology> TOPOLOGIES{
{ Mesh::Topology::POINTS, "points" },

22
libraries/input-plugins/src/input-plugins/KeyboardMouseDevice.cpp
View file

@ -356,17 +356,17 @@ controller::Input KeyboardMouseDevice::InputDevice::makeInput(KeyboardMouseDevic
* new x-coordinate value.</td></tr>
* <tr><td><code>MouseY</code></td><td>number</td><td>number</td><td>The mouse y-coordinate changed. The data value is its
* new y-coordinate value.</td></tr>
* <tr><td><code>MouseWheelRight</code></td><td>number</td><td>number</td><td>The mouse wheel rotated right. The data value
* is the number of units rotated (typically <code>1.0</code>).</td></tr>
* <tr><td><code>MouseWheelLeft</code></td><td>number</td><td>number</td><td>The mouse wheel rotated left. The data value
* is the number of units rotated (typically <code>1.0</code>).</td></tr>
* <tr><td><code>MouseWheelUp</code></td><td>number</td><td>number</td><td>The mouse wheel rotated up. The data value
* is the number of units rotated (typically <code>1.0</code>).
* <tr><td><code>MouseWheelRight</code></td><td>number</td><td>number</td><td>The mouse wheel rotated right or two-finger
* swipe moved right. The data value is the number of units moved (typically <code>1.0</code>).</td></tr>
* <tr><td><code>MouseWheelLeft</code></td><td>number</td><td>number</td><td>The mouse wheel rotated left or two-finger
* swipe moved left. The data value is the number of units moved (typically <code>1.0</code>).</td></tr>
* <tr><td><code>MouseWheelUp</code></td><td>number</td><td>number</td><td>The mouse wheel rotated up or two-finger swipe
* moved up. The data value is the number of units move3d (typically <code>1.0</code>).
* <p><strong>Warning:</strong> The mouse wheel in an ordinary mouse generates left/right wheel events instead of
* up/down.</p>
* </td></tr>
* <tr><td><code>MouseWheelDown</code></td><td>number</td><td>number</td><td>The mouse wheel rotated down. The data value
* is the number of units rotated (typically <code>1.0</code>).
* <tr><td><code>MouseWheelDown</code></td><td>number</td><td>number</td><td>The mouse wheel rotated down or two-finger
* swipe moved down. The data value is the number of units moved (typically <code>1.0</code>).
* <p><strong>Warning:</strong> The mouse wheel in an ordinary mouse generates left/right wheel events instead of
* up/down.</p>
* </td></tr>
@ -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.</td></tr>
* <tr><td><code>TouchpadDown</code></td><td>number</td><td>number</td><td>The average touch on a touch-enabled device
* moved down. The data value is how far the average position of all touch points moved.</td></tr>
* </tbody>
* <tr><td><code>GesturePinchOut</code></td><td>number</td><td>number</td><td>The 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.</td></tr>
* <tr><td><code>GesturePinchOut</code></td><td>number</td><td>number</td><td>The 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.</td></tr>
* </tbody>
* </table>
* @typedef {object} Controller.Hardware-Keyboard
*/

1
libraries/networking/src/ResourceCache.h
View file

@ -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

1
libraries/procedural/src/procedural/Procedural.h
View file

@ -27,7 +27,6 @@ using UniformLambdas = std::list<std::function<void(gpu::Batch& batch)>>;
const size_t MAX_PROCEDURAL_TEXTURE_CHANNELS{ 4 };
/**jsdoc
* An object containing user-defined uniforms for communicating data to shaders.
* @typedef {object} ProceduralUniforms
*/

12
libraries/procedural/src/procedural/ProceduralMaterialCache.cpp
View file

@ -145,7 +145,7 @@ NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMater
* <code>"hifi_pbr"</code> model only.
* @property {string} opacityMapMode - The mode defining the interpretation of the opacity map. Values can be:
* <ul>
* <li><code>"OPACITY_MAP_OPAQUE"</code> for ignoring the <code>opacityMap</code> information.</li>
* <li><code>"OPACITY_MAP_OPAQUE"</code> for ignoring the opacity map information.</li>
* <li><code>"OPACITY_MAP_MASK"</code> for using the <code>opacityMap</code> as a mask, where only the texel greater
* than <code>opacityCutoff</code> are visible and rendered opaque.</li>
* <li><code>"OPACITY_MAP_BLEND"</code> for using the <code>opacityMap</code> for alpha blending the material surface
@ -153,14 +153,14 @@ NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMater
* </ul>
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {number|string} opacityCutoff - The opacity cutoff threshold used to determine the opaque texels of the
* <code>opacityMap</code> when <code>opacityMapMode</code> is <code>"OPACITY_MAP_MASK"</code>, range <code>0.0</code>
* <code>opacityMap</code> when <code>opacityMapMode</code> is <code>"OPACITY_MAP_MASK"</code>. Range <code>0.0</code>
* &ndash; <code>1.0</code>.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> 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:
* <ul>
* <li><code>"CULL_NONE"</code> for rendering both sides of the geometry.</li>
* <li><code>"CULL_FRONT"</code> for culling the front faces of the geometry.</li>
* <li><code>"CULL_BACK"</code> (the default) for culling the back faces of the geometry.</li>
* <li><code>"CULL_NONE"</code> to render both sides of the geometry.</li>
* <li><code>"CULL_FRONT"</code> to cull the front faces of the geometry.</li>
* <li><code>"CULL_BACK"</code> (the default) to cull the back faces of the geometry.</li>
* </ul>
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* @property {string} roughnessMap - The URL of the roughness texture image. You can use this or <code>glossMap</code>, but not

2
libraries/script-engine/src/AssetScriptingInterface.cpp
View file

@ -419,7 +419,7 @@ void AssetScriptingInterface::compressData(QScriptValue options, QScriptValue sc
* <code>false</code> to upload and store the data without gzip compression. Synonym: <code>compressed</code>.
* @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
* <code>"atp:"</code>. IF not specified, no path-to-hash mapping is set.
* <code>"atp:"</code>. If not specified, no path-to-hash mapping is set.
* <p>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.</p>
*/

60
libraries/script-engine/src/ModelScriptingInterface.h
View file

@ -17,19 +17,79 @@
#include <RegisteredMetaTypes.h>
class QScriptEngine;
/**jsdoc
* The <code>Model</code> 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}.
* <p>See also, the {@link Graphics} API.</p>
*
* @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. <code>false</code> 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<glm::vec3>& vertices,
const QVector<glm::vec3>& normals,
const QVector<MeshFace>& 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. <code>false</code> 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. <code>false</code> if an error.
*/
Q_INVOKABLE QScriptValue getVertex(MeshProxy* meshProxy, int vertexIndex);
private:

62
libraries/script-engine/src/ScriptEngine.cpp
View file

@ -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<void(const EntityItemID&)>;
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<void(const EntityItemID&, const PointerEvent&)>;
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<void(const EntityItemID&, const EntityItemID&, const Collision&)>;
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
* <p>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.</p>
* <p>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.</p>
* <table>
* <thead>
* <tr><th>Event Name</th><th>Entity Event</th></tr>
* <tr><th>Event Name</th><th>Callback Type</th><th>Entity Event</th></tr>
* </thead>
* <tbody>
* <tr><td><code>"enterEntity"</code></td><td>{@link Entities.enterEntity}</td></tr>
* <tr><td><code>"leaveEntity"</code></td><td>{@link Entities.leaveEntity}</td></tr>
* <tr><td><code>"mousePressOnEntity"</code></td><td>{@link Entities.mousePressOnEntity}</td></tr>
* <tr><td><code>"mouseMoveOnEntity"</code></td><td>{@link Entities.mouseMoveOnEntity}</td></tr>
* <tr><td><code>"mouseReleaseOnEntity"</code></td><td>{@link Entities.mouseReleaseOnEntity}</td></tr>
* <tr><td><code>"clickDownOnEntity"</code></td><td>{@link Entities.clickDownOnEntity}</td></tr>
* <tr><td><code>"holdingClickOnEntity"</code></td><td>{@link Entities.holdingClickOnEntity}</td></tr>
* <tr><td><code>"clickReleaseOnEntity"</code></td><td>{@link Entities.clickReleaseOnEntity}</td></tr>
* <tr><td><code>"hoverEnterEntity"</code></td><td>{@link Entities.hoverEnterEntity}</td></tr>
* <tr><td><code>"hoverOverEntity"</code></td><td>{@link Entities.hoverOverEntity}</td></tr>
* <tr><td><code>"hoverLeaveEntity"</code></td><td>{@link Entities.hoverLeaveEntity}</td></tr>
* <tr><td><code>"collisionWithEntity"</code></td><td>{@link Entities.collisionWithEntity}</td></tr>
* <tr><td><code>"enterEntity"</code></td><td>{@link Script~entityEventCallback|entityEventCallback}</td>
* <td>{@link Entities.enterEntity}</td></tr>
* <tr><td><code>"leaveEntity"</code></td><td>{@link Script~entityEventCallback|entityEventCallback}</td>
* <td>{@link Entities.leaveEntity}</td></tr>
* <tr><td><code>"mousePressOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.mousePressOnEntity}</td></tr>
* <tr><td><code>"mouseMoveOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.mouseMoveOnEntity}</td></tr>
* <tr><td><code>"mouseReleaseOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.mouseReleaseOnEntity}</td></tr>
* <tr><td><code>"clickDownOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.clickDownOnEntity}</td></tr>
* <tr><td><code>"holdingClickOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.holdingClickOnEntity}</td></tr>
* <tr><td><code>"clickReleaseOnEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.clickReleaseOnEntity}</td></tr>
* <tr><td><code>"hoverEnterEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.hoverEnterEntity}</td></tr>
* <tr><td><code>"hoverOverEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.hoverOverEntity}</td></tr>
* <tr><td><code>"hoverLeaveEntity"</code></td><td>{@link Script~pointerEventCallback|pointerEventCallback}</td>
* <td>{@link Entities.hoverLeaveEntity}</td></tr>
* <tr><td><code>"collisionWithEntity"</code><td>{@link Script~collisionEventCallback|collisionEventCallback}</td>
* </td><td>{@link Entities.collisionWithEntity}</td></tr>
* </tbody>
* </table>
*
* @typedef {string} Script.EntityEvent
*/
connect(entities.data(), &EntityScriptingInterface::enterEntity, this, makeSingleEntityHandler("enterEntity"));

8
libraries/script-engine/src/ScriptEngine.h
View file

@ -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.
* <p>See also, the {@link Entities} API.</p>
* @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 <caption>Report when a mouse press occurs on a particular entity.</caption>
* var entityID = Entities.addEntity({
* type: "Box",

1
libraries/script-engine/src/ScriptsModel.h
View file

@ -87,7 +87,6 @@ public:
* </ul>
*
* @class ScriptsModel
* @hideconstructor
*
* @hifi-interface

2
libraries/script-engine/src/WebSocketClass.h
View file

@ -21,7 +21,7 @@
* near-complete implementation of the WebSocket API described in the Mozilla docs:
* <a href="https://developer.mozilla.org/en-US/docs/Web/API/WebSocket">https://developer.mozilla.org/en-US/docs/Web/API/WebSocket</a>.
*
* <p>Constructed by <code>new WebSocket(...)</code> in Interface, client entity, avatar, and server entity scripts, or the
* <p>Create using <code>new WebSocket(...)</code> in Interface, client entity, avatar, and server entity scripts, or the
* {@link WebSocketServer} class in server entity and assignment client scripts.
*
* <p><strong>Note:</strong> Does not support secure, <code>wss:</code> protocol.</p>

2
libraries/script-engine/src/WebSocketServerClass.h
View file

@ -20,6 +20,8 @@
/**jsdoc
* Manages {@link WebSocket}s in server entity and assignment client scripts.
*
* <p>Create using <code>new WebSocketServer(...)</code>.</p>
*
* @class WebSocketServer
*
* @hifi-server-entity

2
libraries/script-engine/src/XMLHttpRequestClass.h
View file

@ -61,6 +61,8 @@ XMlHttpRequest.getResponseHeader(QString) function
* the Mozilla docs:
* <a href="https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest">https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest</a>.
*
* <p>Create using <code>new XMLHttpRequest(...)</code>.</p>
*
* @class XMLHttpRequest
*
* @hifi-interface

1
libraries/shared/src/JointData.h
View file

@ -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;

5
libraries/shared/src/RegisteredMetaTypes.cpp
View file

@ -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));

10
libraries/shared/src/RegisteredMetaTypes.h
View file

@ -687,8 +687,10 @@ namespace graphics {
using MeshPointer = std::shared_ptr<graphics::Mesh>;
/**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
* @hideconstructor
*
* @hifi-interface
* @hifi-client-entity
@ -705,16 +707,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;

4
libraries/ui/src/QmlWebWindowClass.h
View file

@ -14,6 +14,8 @@
/**jsdoc
* A <code>OverlayWebWindow</code> displays an HTML window inside Interface.
*
* <p>Create using <code>new OverlayWebWindow(...)</code>.</p>
*
* @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
@ -106,7 +108,7 @@
* }, 2000);
*
* @example
* // HTML file, "OverlayWebWindow.qml".
* // HTML file, "OverlayWebWindow.html".
*
* <!DOCTYPE html>
* <html>

2
libraries/ui/src/QmlWindowClass.h
View file

@ -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.</p>
*
* <p>Create using <code>new OverlayWindow(...)</code>.</p>
*
* @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.

8
libraries/ui/src/ui/TabletScriptingInterface.h
View file

@ -217,6 +217,7 @@ Q_DECLARE_METATYPE(TabletButtonsProxyModel*);
* <p>Retrieve an existing tablet or create a new tablet using {@link Tablet.getTablet}.</p>
*
* @class TabletProxy
* @hideconstructor
*
* @hifi-interface
* @hifi-client-entity
@ -422,6 +423,12 @@ public:
* <pre class="prettyprint"><code>EventBridge.scriptEventReceived.connect(function(message) {
* ...
* });</code></pre>
* <p><strong>Warning:</strong> The <code>EventBridge</code> 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
* <code>EventBridge.scriptEventReceived.connect(...)</code>. A better solution is to periodically call
* <code>EventBridge.scriptEventReceived.connect(...)</code> and then <code>EventBridge.emitWebEvent(...)</code> to send a
* message to the Interface script, and have that send a message back using <code>emitScriptEvent(...)</code>; when the
* return message is received, the <codE>EventBridge</code> is ready for use.</p>
* @function TabletProxy#emitScriptEvent
* @param {string|object} message - The message to send to the web page.
*/
@ -586,6 +593,7 @@ Q_DECLARE_METATYPE(TabletProxy*);
* <p>Create a new button using {@link TabletProxy#addButton}.</p>
*
* @class TabletButtonProxy
* @hideconstructor
*
* @hifi-interface
* @hifi-client-entity

2
tools/jsdoc/hifi-jsdoc-template/tmpl/container.tmpl
View file

@ -75,7 +75,7 @@
<?js doc.modules.forEach(function(module) { ?>
<?js= self.partial('methodList.tmpl', module) ?>
<?js }) ?>
<?js } else if (doc.kind === 'class' || (doc.kind === 'namespace' && doc.signature)) { ?>
<?js } else if ((doc.kind === 'class' && !doc.hideconstructor) || (doc.kind === 'namespace' && doc.signature)) { ?>
<h3>Description</h3>
<div><?js= doc.description ?></div>
<?js= self.partial('details.tmpl', doc) ?>

2
tools/jsdoc/hifi-jsdoc-template/tmpl/details.tmpl
View file

@ -19,7 +19,7 @@ if (data.defaultvalue && (data.defaultvaluetype === 'object' || data.defaultvalu
<?js
var properties = data.properties;
if (properties && properties.length && properties.forEach && !data.hideconstructor) {
if (properties && properties.length && properties.forEach) {
?>
<h3 class="propsHeading" id="props">Properties</h3>