From ade85ad8c089306ed822f1e50afe30cd4a0fd33d Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 30 Jul 2019 10:41:07 +1200 Subject: [PATCH] Update API JSDoc with glTF --- .../src/avatars/ScriptableAvatar.h | 6 ++-- interface/src/avatar/MyAvatar.h | 35 +++++++++++-------- interface/src/ui/overlays/Overlays.cpp | 4 ++- libraries/avatars/src/AvatarData.cpp | 3 +- libraries/avatars/src/AvatarData.h | 9 +++-- .../entities/src/AnimationPropertyGroup.cpp | 6 ++-- .../entities/src/EntityItemProperties.cpp | 4 +-- libraries/entities/src/EntityTypes.h | 2 +- libraries/shared/src/RegisteredMetaTypes.cpp | 6 ++-- 9 files changed, 45 insertions(+), 30 deletions(-) diff --git a/assignment-client/src/avatars/ScriptableAvatar.h b/assignment-client/src/avatars/ScriptableAvatar.h index 3ef908bedb..fc796b418f 100644 --- a/assignment-client/src/avatars/ScriptableAvatar.h +++ b/assignment-client/src/avatars/ScriptableAvatar.h @@ -97,8 +97,10 @@ public: /**jsdoc * Starts playing an animation on the avatar. * @function Avatar.startAnimation - * @param {string} url - The animation file's URL. Animation files need to be in the FBX format but only need to contain - * the avatar skeleton and animation data. + * @param {string} url - The animation file's URL. Animation files need to 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 + * respectively). + *

Warning: glTF animations currently do not always animate correctly.

* @param {number} [fps=30] - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. * @param {number} [priority=1] - Not used. * @param {boolean} [loop=false] - true if the animation should loop, false if it shouldn't. diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index db373c6402..31fbba03ae 100644 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -609,8 +609,10 @@ public: * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see * Avatar Standards.

* @function MyAvatar.overrideAnimation - * @param {string} url - The URL to the animation file. Animation files need to be FBX format, but only need to contain the - * avatar skeleton and animation data. + * @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 + * respectively). + *

Warning: glTF animations currently do not always animate correctly.

* @param {number} fps - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. * @param {boolean} loop - true if the animation should loop, false if it shouldn't. * @param {number} firstFrame - The frame to start the animation at. @@ -630,8 +632,10 @@ public: * Use {@link MyAvatar.restoreHandAnimation} to restore the default poses. * @function MyAvatar.overrideHandAnimation * @param isLeft {boolean} true to override the left hand, false to override the right hand. - * @param {string} url - The URL of the animation file. Animation files need to be FBX format, but only need to contain the - * avatar skeleton and animation data. + * @param {string} url - The URL of the animation file. Animation files need to 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 + * respectively). + *

Warning: glTF animations currently do not always animate correctly.

* @param {number} fps - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. * @param {boolean} loop - true if the animation should loop, false if it shouldn't. * @param {number} firstFrame - The frame to start the animation at. @@ -702,19 +706,22 @@ public: *

Each avatar has an avatar-animation.json file that defines a set of animation roles. Animation roles map to easily * understandable actions that the avatar can perform, such as "idleStand", "idleTalk", or * "walkFwd". To get the full list of roles, use {@ link MyAvatar.getAnimationRoles}. - * For each role, the avatar-animation.json defines when the animation is used, the animation clip (FBX) used, and how - * animations are blended together with procedural data (such as look at vectors, hand sensors etc.). - * overrideRoleAnimation() is used to change the animation clip (FBX) associated with a specified animation - * role. To end the role animation and restore the default, use {@link MyAvatar.restoreRoleAnimation}.

- *

Note: Hand roles only affect the hand. Other 'main' roles, like 'idleStand', 'idleTalk', 'takeoffStand' are full body.

+ * For each role, the avatar-animation.json defines when the animation is used, the animation clip (glTF or FBX) used, and + * how animations are blended together with procedural data (such as look at vectors, hand sensors etc.). + * overrideRoleAnimation() is used to change the animation clip (glTF or FBX) associated with a specified + * animation role. To end the role animation and restore the default, use {@link MyAvatar.restoreRoleAnimation}.

+ *

Note: Hand roles only affect the hand. Other "main" roles, like "idleStand", "idleTalk", and "takeoffStand", are full + * body.

*

Note: When using pre-built animation data, it's critical that the joint orientation of the source animation and target * rig are equivalent, since the animation data applies absolute values onto the joints. If the orientations are different, * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see * Avatar Standards. * @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 FBX format, but only need to contain - * the avatar skeleton and animation data. + * @param {string} url - The URL to the animation file. Animation files need to 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 + * respectively). + *

Warning: glTF animations currently do not always animate correctly.

* @param {number} fps - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. * @param {boolean} loop - true if the animation should loop, false if it shouldn't. * @param {number} firstFrame - The frame the animation should start at. @@ -739,9 +746,9 @@ public: *

Each avatar has an avatar-animation.json file that defines a set of animation roles. Animation roles map to easily * understandable actions that the avatar can perform, such as "idleStand", "idleTalk", or * "walkFwd". To get the full list of roles, use {@link MyAvatar.getAnimationRoles}. For each role, - * the avatar-animation.json defines when the animation is used, the animation clip (FBX) used, and how animations are - * blended together with procedural data (such as look-at vectors, hand sensors etc.). You can change the animation clip - * (FBX) associated with a specified animation role using {@link MyAvatar.overrideRoleAnimation}. + * the avatar-animation.json defines when the animation is used, the animation clip (glTF or FBX) used, and how animations + * are blended together with procedural data (such as look-at vectors, hand sensors etc.). You can change the animation + * clip (glTF or FBX) associated with a specified animation role using {@link MyAvatar.overrideRoleAnimation}. * restoreRoleAnimation() is used to restore a specified animation role's default animation clip. If you have * not specified an override animation for the specified role, this function has no effect. * @function MyAvatar.restoreRoleAnimation diff --git a/interface/src/ui/overlays/Overlays.cpp b/interface/src/ui/overlays/Overlays.cpp index be371c900b..100711d69b 100644 --- a/interface/src/ui/overlays/Overlays.cpp +++ b/interface/src/ui/overlays/Overlays.cpp @@ -1740,7 +1740,9 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { * parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather * than a joint. * - * @property {string} url - The URL of the FBX or OBJ model used for the overlay. + * @property {string} url - The URL of the glTF, FBX, or OBJ model used for the overlay. glTF models may be in JSON or binary + * format (".gltf" or ".glb" URLs respectively). Baked models' URLs have ".baked" before the file type. Model files may + * also be compressed in GZ format, in which case the URL ends in ".gz". * @property {number} loadPriority=0.0 - The priority for loading and displaying the overlay. Overlays with higher values load * first. Currently not used. * @property {Object.|string} textures - Texture name, URL pairs used when rendering the model in place of the diff --git a/libraries/avatars/src/AvatarData.cpp b/libraries/avatars/src/AvatarData.cpp index 22b070464d..7d5f38db40 100755 --- a/libraries/avatars/src/AvatarData.cpp +++ b/libraries/avatars/src/AvatarData.cpp @@ -2860,7 +2860,8 @@ glm::vec3 AvatarData::getAbsoluteJointTranslationInObjectFrame(int index) const /**jsdoc * Information on an attachment worn by the avatar. * @typedef {object} AttachmentData - * @property {string} modelUrl - The URL of the model file. Models can be FBX or OBJ format. + * @property {string} modelUrl - The URL of the glTF, FBX, or OBJ model file. glTF models may be in JSON or binary format + * (".gltf" or ".glb" URLs respectively). * @property {string} jointName - The name of the joint that the attachment is parented to. * @property {Vec3} translation - The offset from the joint that the attachment is positioned at. * @property {Vec3} rotation - The rotation applied to the model relative to the joint orientation. diff --git a/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index 3c8e2d6fcc..375f2e13de 100755 --- a/libraries/avatars/src/AvatarData.h +++ b/libraries/avatars/src/AvatarData.h @@ -1268,12 +1268,11 @@ public: /**jsdoc * Attaches a model to your avatar. For example, you can give your avatar a hat to wear, a guitar to hold, or a surfboard to * stand on. - *

Note: Attached models are models only; they are not entities and can not be manipulated using the {@link Entities} API. - * Nor can you use this function to attach an entity (such as a sphere or a box) to your avatar.

* @function Avatar.attach - * @param {string} modelURL - The URL of the model to attach. Models can be .FBX or .OBJ format. - * @param {string} [jointName=""] - The name of the avatar joint (see {@link MyAvatar.getJointNames} or {@link Avatar.getJointNames}) to attach the model - * to. + * @param {string} modelURL - The URL of the glTF, FBX, or OBJ model to attach. glTF models may be in JSON or binary format + * (".gltf" or ".glb" URLs respectively). + * @param {string} [jointName=""] - The name of the avatar joint (see {@link MyAvatar.getJointNames} or + * {@link Avatar.getJointNames}) to attach the model to. * @param {Vec3} [translation=Vec3.ZERO] - The offset to apply to the model relative to the joint position. * @param {Quat} [rotation=Quat.IDENTITY] - The rotation to apply to the model relative to the joint orientation. * @param {number} [scale=1.0] - The scale to apply to the model. diff --git a/libraries/entities/src/AnimationPropertyGroup.cpp b/libraries/entities/src/AnimationPropertyGroup.cpp index 7f9225bd6c..38230b4f50 100644 --- a/libraries/entities/src/AnimationPropertyGroup.cpp +++ b/libraries/entities/src/AnimationPropertyGroup.cpp @@ -50,8 +50,10 @@ bool operator!=(const AnimationPropertyGroup& a, const AnimationPropertyGroup& b /**jsdoc * An animation is configured by the following properties: * @typedef {object} Entities.AnimationProperties - * @property {string} url="" - The URL of the FBX file that has the animation. - * @property {boolean} allowTranslation=true - true to enable translations contained in the animation to be + * @property {string} url="" - The URL of the glTF or FBX file that has the animation. glTF files may be in JSON or binary + * format (".gltf" or ".glb" URLs respectively). + *

Warning: glTF animations currently do not always animate correctly.

+ * @property {boolean} allowTranslation=true - true to enable translations contained in the animation to be * played, false to disable translations. * @property {number} fps=30 - The speed in frames/s that the animation is played at. * @property {number} firstFrame=0 - The first frame to play in the animation. diff --git a/libraries/entities/src/EntityItemProperties.cpp b/libraries/entities/src/EntityItemProperties.cpp index b89788040f..88ee3c6569 100644 --- a/libraries/entities/src/EntityItemProperties.cpp +++ b/libraries/entities/src/EntityItemProperties.cpp @@ -958,8 +958,8 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { * value is specified then the model is automatically sized to its * {@link Entities.EntityProperties|naturalDimensions}. * @property {string} modelURL="" - The URL of the glTF, FBX, or OBJ model. glTF models may be in JSON or binary format - * (".gltf" or ".glb" URLs respectively). Baked FBX models' URLs end in ".baked.fbx". Model files may also be compressed in GZ - * format, in which case the URL ends in ".gz". + * (".gltf" or ".glb" URLs respectively). Baked models' URLs have ".baked" before the file type. Model files may also be + * compressed in GZ format, in which case the URL ends in ".gz". * @property {Vec3} modelScale - The scale factor applied to the model's dimensions. *

Deprecated: This property is deprecated and will be removed.

* @property {string} textures="" - A JSON string of texture name, URL pairs used when rendering the model in place of the diff --git a/libraries/entities/src/EntityTypes.h b/libraries/entities/src/EntityTypes.h index 8fdc752cac..4106eb8054 100644 --- a/libraries/entities/src/EntityTypes.h +++ b/libraries/entities/src/EntityTypes.h @@ -59,7 +59,7 @@ public: * "Sphere". If an entity of type Box or Shape has its shape set * to "Sphere" then its type will be reported as "Sphere". * {@link Entities.EntityProperties-Sphere|EntityProperties-Sphere} - * "Model"A mesh model from a glTf, FBX, or OBJ file. + * "Model"A mesh model from a glTF, FBX, or OBJ file. * {@link Entities.EntityProperties-Model|EntityProperties-Model} * "Text"A pane of text oriented in space. * {@link Entities.EntityProperties-Text|EntityProperties-Text} diff --git a/libraries/shared/src/RegisteredMetaTypes.cpp b/libraries/shared/src/RegisteredMetaTypes.cpp index e23064c8a0..d6ce2f11b1 100644 --- a/libraries/shared/src/RegisteredMetaTypes.cpp +++ b/libraries/shared/src/RegisteredMetaTypes.cpp @@ -1229,8 +1229,10 @@ AnimationDetails::AnimationDetails(QString role, QUrl url, float fps, float prio * The details of an animation that is playing. * @typedef {object} Avatar.AnimationDetails * @property {string} role - Not used. - * @property {string} url - The URL to the animation file. Animation files need to be in .FBX format but only need to contain -* the avatar skeleton and animation data. + * @property {string} url - The URL to the animation file. Animation files need to 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 + * respectively). + *

Warning: glTF animations currently do not always animate correctly.

* @property {number} fps - The frames per second(FPS) rate for the animation playback. 30 FPS is normal speed. * @property {number} priority - Not used. * @property {boolean} loop - true if the animation should loop, false if it shouldn't.