Merge pull request #15263 from ctrlaltdavid/M21460

AnimationCache, ModelCache, SoundCache, and TextureCache JSDoc

libraries/animation/src/AnimationCache.h

@@ -45,18 +45,6 @@ private:
 
 Q_DECLARE_METATYPE(AnimationPointer)
 
-/**jsdoc
- * @class AnimationObject
- *
- * @hifi-interface
- * @hifi-client-entity
- * @hifi-avatar
- * @hifi-server-entity
- * @hifi-assignment-client
- *
- * @property {string[]} jointNames
- * @property {FBXAnimationFrame[]} frames
- */
 /// An animation loaded from the network.
 class Animation : public Resource {
     Q_OBJECT
@@ -72,16 +60,8 @@ public:
 
     virtual bool isLoaded() const override;
 
-    /**jsdoc
-     * @function AnimationObject.getJointNames
-     * @returns {string[]}
-     */
     Q_INVOKABLE QStringList getJointNames() const;
     
-    /**jsdoc
-     * @function AnimationObject.getFrames
-     * @returns {FBXAnimationFrame[]}
-     */
     Q_INVOKABLE QVector<HFMAnimationFrame> getFrames() const;
 
     const QVector<HFMAnimationFrame>& getFramesReference() const;

libraries/animation/src/AnimationCacheScriptingInterface.h

@@ -25,7 +25,8 @@ class AnimationCacheScriptingInterface : public ScriptableResourceCache, public
     // Properties are copied over from ResourceCache (see ResourceCache.h for reason).
 
     /**jsdoc
-     * API to manage animation cache resources.
+     * The <code>AnimationCache</code> API manages animation cache resources.
+     *
      * @namespace AnimationCache
      *
      * @hifi-interface
@@ -48,10 +49,10 @@ public:
     AnimationCacheScriptingInterface();
 
     /**jsdoc
-     * Returns animation resource for particular animation.
+     * Gets information about an animation resource.
      * @function AnimationCache.getAnimation
-     * @param {string} url - URL to load.
+     * @param {string} url - The URL of the animation.
-     * @returns {AnimationObject} animation
+     * @returns {AnimationObject} An animation object.
      */
     Q_INVOKABLE AnimationPointer getAnimation(const QString& url);
 };

libraries/animation/src/AnimationObject.h

@@ -19,6 +19,20 @@
 
 class QScriptEngine;
 
+/**jsdoc
+ * Information about an animation resource, created by {@link AnimationCache.getAnimation}.
+ *
+ * @class AnimationObject
+ *
+ * @hifi-interface
+ * @hifi-client-entity
+ * @hifi-avatar
+ * @hifi-server-entity
+ * @hifi-assignment-client
+ *
+ * @property {string[]} jointNames - The names of the joints that are animated. <em>Read-only.</em>
+ * @property {AnimationFrameObject[]} frames - The frames in the animation. <em>Read-only.</em>
+ */
 /// Scriptable wrapper for animation pointers.
 class AnimationObject : public QObject, protected QScriptable {
     Q_OBJECT
@@ -27,11 +41,34 @@ class AnimationObject : public QObject, protected QScriptable {
 
 public:
     
+    /**jsdoc
+     * Gets the names of the joints that are animated.
+     * @function AnimationObject.getJointNames
+     * @returns {string[]} The names of the joints that are animated.
+     */
     Q_INVOKABLE QStringList getJointNames() const;
     
+    /**jsdoc
+     * Gets the frames in the animation.
+     * @function AnimationObject.getFrames
+     * @returns {AnimationFrameObject[]} The frames in the animation.
+     */
     Q_INVOKABLE QVector<HFMAnimationFrame> getFrames() const;
 };
 
+/**jsdoc
+ * Joint rotations in one frame of an animation.
+ *
+ * @class AnimationFrameObject
+ *
+ * @hifi-interface
+ * @hifi-client-entity
+ * @hifi-avatar
+ * @hifi-server-entity
+ * @hifi-assignment-client
+ *
+ * @property {Quat[]} rotations - Joint rotations. <em>Read-only.</em>
+ */
 /// Scriptable wrapper for animation frames.
 class AnimationFrameObject : public QObject, protected QScriptable {
     Q_OBJECT
@@ -39,6 +76,11 @@ class AnimationFrameObject : public QObject, protected QScriptable {
 
 public:
     
+    /**jsdoc
+     * Gets the joint rotations in the animation frame.
+     * @function AnimationFrameObject.getRotations
+     * @returns {Quat[]} The joint rotations in the animation frame.
+     */
     Q_INVOKABLE QVector<glm::quat> getRotations() const;
 };
 

libraries/audio/src/Sound.h

@@ -124,9 +124,9 @@ typedef QSharedPointer<Sound> SharedSoundPointer;
  * An audio resource, created by {@link SoundCache.getSound}, to be played back using {@link Audio.playSound}.
  * <p>Supported formats:</p>
  * <ul>
- *   <li>WAV: 16-bit uncompressed WAV at any sample rate, with 1 (mono), 2(stereo), or 4 (ambisonic) channels.</li>
+ *   <li>WAV: 16-bit uncompressed WAV at any sample rate, with 1 (mono), 2 (stereo), or 4 (ambisonic) channels.</li>
  *   <li>MP3: Mono or stereo, at any sample rate.</li>
- *   <li>RAW: 48khz 16-bit mono or stereo. Filename must include <code>".stereo"</code> to be interpreted as stereo.</li>
+ *   <li>RAW: 48khz 16-bit mono or stereo. File name must include <code>".stereo"</code> to be interpreted as stereo.</li>
  * </ul>
  *
  * @class SoundObject
@@ -138,8 +138,8 @@ typedef QSharedPointer<Sound> SharedSoundPointer;
  * @hifi-assignment-client
  *
  * @property {boolean} downloaded - <code>true</code> if the sound has been downloaded and is ready to be played, otherwise 
- *     <code>false</code>.
+ *     <code>false</code>. <em>Read-only.</em>
- * @property {number} duration - The duration of the sound, in seconds.
+ * @property {number} duration - The duration of the sound, in seconds. <em>Read-only.</em>
  */
 class SoundScriptingInterface : public QObject {
     Q_OBJECT

libraries/audio/src/SoundCacheScriptingInterface.h

@@ -25,7 +25,8 @@ class SoundCacheScriptingInterface : public ScriptableResourceCache, public Depe
     // Properties are copied over from ResourceCache (see ResourceCache.h for reason).
 
     /**jsdoc
-     * API to manage sound cache resources.
+     * The <code>SoundCache</code> API manages sound cache resources.
+     *
      * @namespace SoundCache
      *
      * @hifi-interface

libraries/hfm/src/hfm/HFM.h

@@ -251,11 +251,6 @@ public:
     bool wasCompressed { false };
 };
 
-/**jsdoc
- * @typedef {object} FBXAnimationFrame
- * @property {Quat[]} rotations
- * @property {Vec3[]} translations
- */
 /// A single animation frame.
 class AnimationFrame {
 public:

libraries/image/src/image/TextureProcessing.h

@@ -25,6 +25,32 @@ namespace image {
 
 namespace TextureUsage {
 
+/**jsdoc
+ * <p>Describes the type of texture.</p>
+ * <p>See also: {@link Material} and 
+ * {@link https://docs.highfidelity.com/create/3d-models/pbr-materials-guide.html|PBR Materials Guide}.</p>
+ * <table>
+ *   <thead>
+ *     <tr><th>Value</th><th>Name</th><th>Description</th></tr>
+ *   </thead>
+ *   <tbody>
+ *     <tr><td><code>0</code></td><td>Default</td><td>Basic color.</td></tr>
+ *     <tr><td><code>1</code></td><td>Strict</td><td>Basic color. Quality never downgraded.</td></tr>
+ *     <tr><td><code>2</code></td><td>Albedo</td><td>Color for PBR.</td></tr>
+ *     <tr><td><code>3</code></td><td>Normal</td><td>Normal map.</td></tr>
+ *     <tr><td><code>4</code></td><td>Bump</td><td>Bump map.</td></tr>
+ *     <tr><td><code>5</code></td><td>Specular or metallic</td><td>Metallic or not.</td></tr>
+ *     <tr><td><code>6</code></td><td>Roughness</td><td>Rough or matte.</td></tr>
+ *     <tr><td><code>7</code></td><td>Gloss</td><td>Gloss or shine.</td></tr>
+ *     <tr><td><code>8</code></td><td>Emissive</td><td>The amount of light reflected.</td></tr>
+ *     <tr><td><code>9</code></td><td>Cube</td><td>Cubic image for sky boxes.</td></tr>
+ *     <tr><td><code>10</code></td><td>Occlusion or scattering</td><td>How objects or human skin interact with light.</td></tr>
+ *     <tr><td><code>11</code></td><td>Lightmap</td><td>Light map.</td></tr>
+ *     <tr><td><code>12</code></td><td>Unused</td><td>Texture is not currently used.</td></tr>
+ *   </tbody>
+ * </table>
+ * @typedef {number} TextureCache.TextureType
+ */
 enum Type {
     DEFAULT_TEXTURE,
     STRICT_TEXTURE,

libraries/material-networking/src/material-networking/TextureCacheScriptingInterface.h

@@ -25,7 +25,8 @@ class TextureCacheScriptingInterface : public ScriptableResourceCache, public De
     // Properties are copied over from ResourceCache (see ResourceCache.h for reason).
 
     /**jsdoc
-     * API to manage texture cache resources.
+     * The <code>TextureCache</code> API manages texture cache resources.
+     *
      * @namespace TextureCache
      *
      * @hifi-interface
@@ -47,11 +48,14 @@ public:
     TextureCacheScriptingInterface();
 
     /**jsdoc
+     * Prefetches a texture resource of specific type.
      * @function TextureCache.prefetch
-     * @param {string} url
+     * @variation 0
-     * @param {number} type
+     * @param {string} url - The URL of the texture to prefetch.
-     * @param {number} [maxNumPixels=67108864]
+     * @param {TextureCache.TextureType} type - The type of the texture.
-     * @returns {ResourceObject}
+     * @param {number} [maxNumPixels=67108864] - The maximum number of pixels to use for the image. If the texture has more 
+     *     than this number it is downscaled.
+     * @returns {ResourceObject} A resource object.
      */
     Q_INVOKABLE ScriptableResource* prefetch(const QUrl& url, int type, int maxNumPixels = ABSOLUTE_MAX_TEXTURE_NUM_PIXELS);
 
@@ -59,6 +63,7 @@ signals:
     /**jsdoc
      * @function TextureCache.spectatorCameraFramebufferReset
      * @returns {Signal}
+     * @deprecated This signal is deprecated and will be removed.
      */
     void spectatorCameraFramebufferReset();
 };

libraries/model-networking/src/model-networking/ModelCacheScriptingInterface.h

@@ -25,7 +25,8 @@ class ModelCacheScriptingInterface : public ScriptableResourceCache, public Depe
     // Properties are copied over from ResourceCache (see ResourceCache.h for reason).
 
     /**jsdoc
-     * API to manage model cache resources.
+     * The <code>ModelCache</code> API manages model cache resources.
+     *
      * @namespace ModelCache
      *
      * @hifi-interface

libraries/networking/src/ResourceCache.h

@@ -91,6 +91,9 @@ private:
 class ScriptableResource : public QObject {
 
     /**jsdoc
+     * Information about a cached resource. Created by {@link AnimationCache.prefetch}, {@link ModelCache.prefetch},
+     * {@link SoundCache.prefetch}, or {@link TextureCache.prefetch}.
+     *
      * @class ResourceObject
      *
      * @hifi-interface
@@ -99,8 +102,8 @@ class ScriptableResource : public QObject {
      * @hifi-server-entity
      * @hifi-assignment-client
      *
-     * @property {string} url - URL of this resource.
+     * @property {string} url - URL of the resource. <em>Read-only.</em>
-     * @property {Resource.State} state - Current loading state.
+     * @property {Resource.State} state - Current loading state. <em>Read-only.</em>
      */
     Q_OBJECT
     Q_PROPERTY(QUrl url READ getURL)
@@ -109,12 +112,13 @@ class ScriptableResource : public QObject {
 public:
 
     /**jsdoc
+     * The loading state of a resource.
      * @typedef {object} Resource.State
      * @property {number} QUEUED - The resource is queued up, waiting to be loaded.
      * @property {number} LOADING - The resource is downloading.
-     * @property {number} LOADED - The resource has finished downloaded by is not complete.
+     * @property {number} LOADED - The resource has finished downloading but is not complete.
      * @property {number} FINISHED - The resource has completely finished loading and is ready.
-     * @property {number} FAILED - Downloading the resource has failed.
+     * @property {number} FAILED - The resource has failed to download.
      */
     enum State {
         QUEUED,
@@ -129,7 +133,7 @@ public:
     virtual ~ScriptableResource() = default;
 
     /**jsdoc
-      * Release this resource.
+      * Releases the resource.
       * @function ResourceObject#release
       */
     Q_INVOKABLE void release();
@@ -144,16 +148,16 @@ public:
 signals:
 
     /**jsdoc
-     * Triggered when download progress for this resource has changed.
+     * Triggered when the resource's download progress changes.
      * @function ResourceObject#progressChanged
-     * @param {number} bytesReceived - Byytes downloaded so far.
+     * @param {number} bytesReceived - Bytes downloaded so far.
      * @param {number} bytesTotal - Total number of bytes in the resource.
      * @returns {Signal}
      */
     void progressChanged(uint64_t bytesReceived, uint64_t bytesTotal);
 
     /**jsdoc
-     * Triggered when resource loading state has changed.
+     * Triggered when the resource's loading state changes.
      * @function ResourceObject#stateChanged
      * @param {Resource.State} state - New state.
      * @returns {Signal}
@@ -317,30 +321,63 @@ public:
     ScriptableResourceCache(QSharedPointer<ResourceCache> resourceCache);
 
     /**jsdoc
-     * Get the list of all resource URLs.
+     * Gets the URLs of all resources in the cache.
      * @function ResourceCache.getResourceList
-     * @returns {string[]}
+     * @returns {string[]} The URLs of all resources in the cache.
+     * @example <caption>Report cached resources.</caption>
+     * // Replace AnimationCache with ModelCache, SoundCache, or TextureCache as appropriate.
+     *
+     * var cachedResources = AnimationCache.getResourceList();
+     * print("Cached resources: " + JSON.stringify(cachedResources));
      */
     Q_INVOKABLE QVariantList getResourceList();
 
     /**jsdoc
      * @function ResourceCache.updateTotalSize
-     * @param {number} deltaSize
+     * @param {number} deltaSize - Delta size.
+     * @deprecated This function is deprecated and will be removed.
      */
     Q_INVOKABLE void updateTotalSize(const qint64& deltaSize);
 
     /**jsdoc
      * Prefetches a resource.
      * @function ResourceCache.prefetch
-     * @param {string} url - URL of the resource to prefetch.
+     * @param {string} url - The URL of the resource to prefetch.
-     * @returns {ResourceObject}
+     * @returns {ResourceObject} A resource object.
+     * @example <caption>Prefetch a resource and wait until it has loaded.</caption>
+     * // Replace AnimationCache with ModelCache, SoundCache, or TextureCache as appropriate.
+     * // TextureCache has its own version of this function.
+     * 
+     * var resourceURL = "https://s3-us-west-1.amazonaws.com/hifi-content/clement/production/animations/sitting_idle.fbx";
+     * var resourceObject = AnimationCache.prefetch(resourceURL);
+     * 
+     * function checkIfResourceLoaded(state) {
+     *     if (state === Resource.State.FINISHED) {
+     *         print("Resource loaded and ready.");
+     *     } else if (state === Resource.State.FAILED) {
+     *         print("Resource not loaded.");
+     *     }
+     * }
+     * 
+     * // Resource may have already been loaded.
+     * print("Resource state: " + resourceObject.state);
+     * checkIfResourceLoaded(resourceObject.state);
+     * 
+     * // Resource may still be loading.
+     * resourceObject.stateChanged.connect(function (state) {
+     *     print("Resource state changed to: " + state);
+     *     checkIfResourceLoaded(state);
+     * });
      */
     Q_INVOKABLE ScriptableResource* prefetch(const QUrl& url) { return prefetch(url, nullptr, std::numeric_limits<size_t>::max()); }
+    
+    // FIXME: This function variation shouldn't be in the API.
     Q_INVOKABLE ScriptableResource* prefetch(const QUrl& url, void* extra, size_t extraHash);
 
 signals:
 
     /**jsdoc
+     * Triggered when the cache content has changed.
      * @function ResourceCache.dirty
      * @returns {Signal}
      */

libraries/networking/src/ResourceScriptingInterface.h

@@ -18,6 +18,8 @@
 #include <DependencyManager.h>
 
 /**jsdoc
+ * The <code>Resources</code> API enables the default location for different resource types to be overridden.
+ *
  * @namespace Resources
  * 
  * @hifi-interface
@@ -32,15 +34,17 @@ class ResourceScriptingInterface : public QObject, public Dependency {
 public:
 
     /**jsdoc
+     * Overrides a path prefix with an alternative path.
      * @function Resources.overrideUrlPrefix
-     * @param {string} prefix
+     * @param {string} prefix - The path prefix to override, e.g., <code>"atp:/"</code>.
-     * @param {string} replacement
+     * @param {string} replacement - The replacement path for the prefix.
      */
     Q_INVOKABLE void overrideUrlPrefix(const QString& prefix, const QString& replacement);
 
     /**jsdoc
+     * Restores the default path for a specified prefix.
      * @function Resources.restoreUrlPrefix
-     * @param {string} prefix
+     * @param {string} prefix - The prefix of the resource to restore the path for.
      */
     Q_INVOKABLE void restoreUrlPrefix(const QString& prefix) {
         overrideUrlPrefix(prefix, "");

libraries/script-engine/src/AudioScriptingInterface.h

@@ -116,15 +116,25 @@ protected:
      * @param {AudioInjector.AudioInjectorOptions} [injectorOptions={}] - Audio injector configuration.
      * @returns {AudioInjector} The audio injector that plays the audio file.
      * @example <caption>Play a sound.</caption>
-     * var sound = SoundCache.getSound(Script.resourcesPath() + "sounds/sample.wav");
+     * var sound = SoundCache.getSound("http://hifi-content.s3.amazonaws.com/ken/samples/forest_ambiX.wav");
-     * var injector;
-     * var injectorOptions = {
-     *     position: MyAvatar.position
-     * };
      * 
-     * Script.setTimeout(function () { // Give the sound time to load.
+     * function playSound() {
-     *     injector = Audio.playSound(sound, injectorOptions);
+     *     var injectorOptions = {
-     * }, 1000);
+     *         position: MyAvatar.position
+     *     };
+     *     var injector = Audio.playSound(sound, injectorOptions);
+     * }
+     * 
+     * function onSoundReady() {
+     *     sound.ready.disconnect(onSoundReady);
+     *     playSound();
+     * }
+     * 
+     * if (sound.downloaded) {
+     *     playSound();
+     * } else {
+     *     sound.ready.connect(onSoundReady);
+     * }
      */
     Q_INVOKABLE ScriptAudioInjector* playSound(SharedSoundPointer sound, const AudioInjectorOptions& injectorOptions = AudioInjectorOptions());
 

libraries/script-engine/src/ScriptEngine.cpp

@@ -579,6 +579,8 @@ static void scriptableResourceFromScriptValue(const QScriptValue& value, Scripta
 }
 
 /**jsdoc
+ * The <code>Resource</code> API provides values that define the possible loading states of a resource.
+ *
  * @namespace Resource
  *
  * @hifi-interface
@@ -587,7 +589,7 @@ static void scriptableResourceFromScriptValue(const QScriptValue& value, Scripta
  * @hifi-server-entity
  * @hifi-assignment-client
  *
- * @property {Resource.State} State
+ * @property {Resource.State} State - The possible loading states of a resource. <em>Read-only.</em>
  */
 static QScriptValue createScriptableResourcePrototype(ScriptEnginePointer engine) {
     auto prototype = engine->newObject();

tools/jsdoc/plugins/hifi.js

@@ -48,7 +48,9 @@ exports.handlers = {
             '../../libraries/fbx/src',
             '../../libraries/graphics/src/graphics/',
             '../../libraries/graphics-scripting/src/graphics-scripting/',
+            '../../libraries/image/src/image',
             '../../libraries/input-plugins/src/input-plugins',
+            '../../libraries/material-networking/src/material-networking/',
             '../../libraries/midi/src',
             '../../libraries/model-networking/src/model-networking/',
             '../../libraries/networking/src',