diff --git a/libraries/animation/src/AnimationCache.h b/libraries/animation/src/AnimationCache.h index 41742c7485..e8bfa75ecb 100644 --- a/libraries/animation/src/AnimationCache.h +++ b/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 getFrames() const; const QVector& getFramesReference() const; diff --git a/libraries/animation/src/AnimationCacheScriptingInterface.h b/libraries/animation/src/AnimationCacheScriptingInterface.h index 06db5ef352..0ceb302913 100644 --- a/libraries/animation/src/AnimationCacheScriptingInterface.h +++ b/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 AnimationCache 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. - * @returns {AnimationObject} animation + * @param {string} url - The URL of the animation. + * @returns {AnimationObject} An animation object. */ Q_INVOKABLE AnimationPointer getAnimation(const QString& url); }; diff --git a/libraries/animation/src/AnimationObject.h b/libraries/animation/src/AnimationObject.h index fc3a351832..303d0e0d9e 100644 --- a/libraries/animation/src/AnimationObject.h +++ b/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. Read-only. + * @property {AnimationFrameObject[]} frames - The frames in the animation. Read-only. + */ /// 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 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. Read-only. + */ /// 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 getRotations() const; }; diff --git a/libraries/audio/src/Sound.h b/libraries/audio/src/Sound.h index f5f47add32..e5ba322599 100644 --- a/libraries/audio/src/Sound.h +++ b/libraries/audio/src/Sound.h @@ -124,9 +124,9 @@ typedef QSharedPointer SharedSoundPointer; * An audio resource, created by {@link SoundCache.getSound}, to be played back using {@link Audio.playSound}. *

Supported formats:

*
    - *
  • WAV: 16-bit uncompressed WAV at any sample rate, with 1 (mono), 2(stereo), or 4 (ambisonic) channels.
    • + *
  • WAV: 16-bit uncompressed WAV at any sample rate, with 1 (mono), 2 (stereo), or 4 (ambisonic) channels.
    • *
  • MP3: Mono or stereo, at any sample rate.
    • - *
  • RAW: 48khz 16-bit mono or stereo. Filename must include ".stereo" to be interpreted as stereo.
    • + *
  • RAW: 48khz 16-bit mono or stereo. File name must include ".stereo" to be interpreted as stereo.
    • *
* * @class SoundObject @@ -138,8 +138,8 @@ typedef QSharedPointer SharedSoundPointer; * @hifi-assignment-client * * @property {boolean} downloaded - true if the sound has been downloaded and is ready to be played, otherwise - * false. - * @property {number} duration - The duration of the sound, in seconds. + * false. Read-only. + * @property {number} duration - The duration of the sound, in seconds. Read-only. */ class SoundScriptingInterface : public QObject { Q_OBJECT diff --git a/libraries/audio/src/SoundCacheScriptingInterface.h b/libraries/audio/src/SoundCacheScriptingInterface.h index 9caa7a8066..ea767e00b4 100644 --- a/libraries/audio/src/SoundCacheScriptingInterface.h +++ b/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 SoundCache API manages sound cache resources. + * * @namespace SoundCache * * @hifi-interface diff --git a/libraries/hfm/src/hfm/HFM.h b/libraries/hfm/src/hfm/HFM.h index 22b089328f..cd1bdf01d4 100644 --- a/libraries/hfm/src/hfm/HFM.h +++ b/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: diff --git a/libraries/image/src/image/TextureProcessing.h b/libraries/image/src/image/TextureProcessing.h index 2fc23b136d..72e2400721 100644 --- a/libraries/image/src/image/TextureProcessing.h +++ b/libraries/image/src/image/TextureProcessing.h @@ -25,6 +25,32 @@ namespace image { namespace TextureUsage { +/**jsdoc + *

Describes the type of texture.

+ *

See also: {@link Material} and + * {@link https://docs.highfidelity.com/create/3d-models/pbr-materials-guide.html|PBR Materials Guide}.

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
ValueNameDescription
0DefaultBasic color.
1StrictBasic color. Quality never downgraded.
2AlbedoColor for PBR.
3NormalNormal map.
4BumpBump map.
5Specular or metallicMetallic or not.
6RoughnessRough or matte.
7GlossGloss or shine.
8EmissiveThe amount of light reflected.
9CubeCubic image for sky boxes.
10Occlusion or scatteringHow objects or human skin interact with light.
11LightmapLight map.
12UnusedTexture is not currently used.
+ * @typedef {number} TextureCache.TextureType + */ enum Type { DEFAULT_TEXTURE, STRICT_TEXTURE, diff --git a/libraries/material-networking/src/material-networking/TextureCacheScriptingInterface.h b/libraries/material-networking/src/material-networking/TextureCacheScriptingInterface.h index 1cc4f4f948..58d2784855 100644 --- a/libraries/material-networking/src/material-networking/TextureCacheScriptingInterface.h +++ b/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 TextureCache 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 - * @param {number} type - * @param {number} [maxNumPixels=67108864] - * @returns {ResourceObject} + * @variation 0 + * @param {string} url - The URL of the texture to prefetch. + * @param {TextureCache.TextureType} type - The type of the texture. + * @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(); }; diff --git a/libraries/model-networking/src/model-networking/ModelCacheScriptingInterface.h b/libraries/model-networking/src/model-networking/ModelCacheScriptingInterface.h index 16532fafc3..cea2a6cd40 100644 --- a/libraries/model-networking/src/model-networking/ModelCacheScriptingInterface.h +++ b/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 ModelCache API manages model cache resources. + * * @namespace ModelCache * * @hifi-interface diff --git a/libraries/networking/src/ResourceCache.h b/libraries/networking/src/ResourceCache.h index 2096213273..e1f3098658 100644 --- a/libraries/networking/src/ResourceCache.h +++ b/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 {Resource.State} state - Current loading state. + * @property {string} url - URL of the resource. Read-only. + * @property {Resource.State} state - Current loading state. Read-only. */ 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); /**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 Report cached resources. + * // 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. - * @returns {ResourceObject} + * @param {string} url - The URL of the resource to prefetch. + * @returns {ResourceObject} A resource object. + * @example Prefetch a resource and wait until it has loaded. + * // 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::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} */ diff --git a/libraries/networking/src/ResourceScriptingInterface.h b/libraries/networking/src/ResourceScriptingInterface.h index 5f81537e99..73e2d8e29c 100644 --- a/libraries/networking/src/ResourceScriptingInterface.h +++ b/libraries/networking/src/ResourceScriptingInterface.h @@ -18,6 +18,8 @@ #include /**jsdoc + * The Resources 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} replacement + * @param {string} prefix - The path prefix to override, e.g., "atp:/". + * @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, ""); diff --git a/libraries/script-engine/src/AudioScriptingInterface.h b/libraries/script-engine/src/AudioScriptingInterface.h index a6801dcdcb..c97ea10329 100644 --- a/libraries/script-engine/src/AudioScriptingInterface.h +++ b/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 Play a sound. - * var sound = SoundCache.getSound(Script.resourcesPath() + "sounds/sample.wav"); - * var injector; - * var injectorOptions = { - * position: MyAvatar.position - * }; + * var sound = SoundCache.getSound("http://hifi-content.s3.amazonaws.com/ken/samples/forest_ambiX.wav"); * - * Script.setTimeout(function () { // Give the sound time to load. - * injector = Audio.playSound(sound, injectorOptions); - * }, 1000); + * function playSound() { + * var injectorOptions = { + * 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()); diff --git a/libraries/script-engine/src/ScriptEngine.cpp b/libraries/script-engine/src/ScriptEngine.cpp index 873e04dd0a..7abb63ca1c 100644 --- a/libraries/script-engine/src/ScriptEngine.cpp +++ b/libraries/script-engine/src/ScriptEngine.cpp @@ -579,6 +579,8 @@ static void scriptableResourceFromScriptValue(const QScriptValue& value, Scripta } /**jsdoc + * The Resource 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. Read-only. */ static QScriptValue createScriptableResourcePrototype(ScriptEnginePointer engine) { auto prototype = engine->newObject(); diff --git a/tools/jsdoc/plugins/hifi.js b/tools/jsdoc/plugins/hifi.js index 5ec94b46aa..f8230b5dea 100644 --- a/tools/jsdoc/plugins/hifi.js +++ b/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',