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..5f5fd839b4 100644 --- a/libraries/audio/src/Sound.h +++ b/libraries/audio/src/Sound.h @@ -126,7 +126,7 @@ typedef QSharedPointer SharedSoundPointer; *
    *
  • 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/Image.h b/libraries/image/src/image/Image.h index 40c31eeeff..5a04e4f2a7 100644 --- a/libraries/image/src/image/Image.h +++ b/libraries/image/src/image/Image.h @@ -25,6 +25,32 @@ namespace image { namespace TextureUsage { +/**jsdoc + *

Signifies what type of texture a texture is.

+ *

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 / MetallicMetallic or not.
6RoughnessRough / matte.
7GlossGloss / shine.
8EmissiveThe amount of light reflected.
9CubeCubic image for sky boxes.
10Occlusion / ScatteringHow objects / human skin interact with light.
11LightmapLight map.
12UnusedTexture is not 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..d74ac97762 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,13 @@ 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} + * @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 +62,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..b91edcdb5f 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,10 +112,11 @@ 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 downloaded but is not complete. * @property {number} FINISHED - The resource has completely finished loading and is ready. * @property {number} FAILED - Downloading the resource has failed. */ @@ -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 wanted. + * + * 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 it's own version of this function. + * + * var resourceURL = "qrc:///avatar/animations/walk_bwd_fast.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 a4fd2540d4..c2798816c9 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-inly. */ static QScriptValue createScriptableResourcePrototype(ScriptEnginePointer engine) { auto prototype = engine->newObject(); diff --git a/tools/jsdoc/plugins/hifi.js b/tools/jsdoc/plugins/hifi.js index b2b91de1c8..6f992c762a 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',