From 5eb6e9dadd5ea993654405a28fdc66b662788f69 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Tue, 26 Nov 2019 17:00:13 +1300
Subject: [PATCH 1/3] Add recently added properties to caches' JSDoc
---
.../animation/src/AnimationCacheScriptingInterface.h | 4 ++++
libraries/audio/src/SoundCacheScriptingInterface.h | 4 ++++
.../material-networking/TextureCacheScriptingInterface.h | 4 ++++
.../src/model-networking/ModelCacheScriptingInterface.h | 4 ++++
libraries/networking/src/ResourceCache.h | 8 +++++---
.../src/procedural/MaterialCacheScriptingInterface.h | 4 ++++
6 files changed, 25 insertions(+), 3 deletions(-)
diff --git a/libraries/animation/src/AnimationCacheScriptingInterface.h b/libraries/animation/src/AnimationCacheScriptingInterface.h
index 0ceb302913..fc31ecaa2b 100644
--- a/libraries/animation/src/AnimationCacheScriptingInterface.h
+++ b/libraries/animation/src/AnimationCacheScriptingInterface.h
@@ -38,6 +38,10 @@ class AnimationCacheScriptingInterface : public ScriptableResourceCache, public
* @property {number} numCached - Total number of cached resource. <em>Read-only.</em>
* @property {number} sizeTotal - Size in bytes of all resources. <em>Read-only.</em>
* @property {number} sizeCached - Size in bytes of all cached resources. <em>Read-only.</em>
+ * @property {number} numGlobalQueriesPending - Total number of global queries pending (across all resource cache managers).
+ * <em>Read-only.</em>
+ * @property {number} numGlobalQueriesLoading - Total number of global queries loading (across all resource cache managers).
+ * <em>Read-only.</em>
*
* @borrows ResourceCache.getResourceList as getResourceList
* @borrows ResourceCache.updateTotalSize as updateTotalSize
diff --git a/libraries/audio/src/SoundCacheScriptingInterface.h b/libraries/audio/src/SoundCacheScriptingInterface.h
index ea767e00b4..28425f0406 100644
--- a/libraries/audio/src/SoundCacheScriptingInterface.h
+++ b/libraries/audio/src/SoundCacheScriptingInterface.h
@@ -39,6 +39,10 @@ class SoundCacheScriptingInterface : public ScriptableResourceCache, public Depe
* @property {number} numCached - Total number of cached resource. <em>Read-only.</em>
* @property {number} sizeTotal - Size in bytes of all resources. <em>Read-only.</em>
* @property {number} sizeCached - Size in bytes of all cached resources. <em>Read-only.</em>
+ * @property {number} numGlobalQueriesPending - Total number of global queries pending (across all resource cache managers).
+ * <em>Read-only.</em>
+ * @property {number} numGlobalQueriesLoading - Total number of global queries loading (across all resource cache managers).
+ * <em>Read-only.</em>
*
* @borrows ResourceCache.getResourceList as getResourceList
* @borrows ResourceCache.updateTotalSize as updateTotalSize
diff --git a/libraries/material-networking/src/material-networking/TextureCacheScriptingInterface.h b/libraries/material-networking/src/material-networking/TextureCacheScriptingInterface.h
index 58d2784855..5ff15c03d9 100644
--- a/libraries/material-networking/src/material-networking/TextureCacheScriptingInterface.h
+++ b/libraries/material-networking/src/material-networking/TextureCacheScriptingInterface.h
@@ -37,6 +37,10 @@ class TextureCacheScriptingInterface : public ScriptableResourceCache, public De
* @property {number} numCached - Total number of cached resource. <em>Read-only.</em>
* @property {number} sizeTotal - Size in bytes of all resources. <em>Read-only.</em>
* @property {number} sizeCached - Size in bytes of all cached resources. <em>Read-only.</em>
+ * @property {number} numGlobalQueriesPending - Total number of global queries pending (across all resource cache managers).
+ * <em>Read-only.</em>
+ * @property {number} numGlobalQueriesLoading - Total number of global queries loading (across all resource cache managers).
+ * <em>Read-only.</em>
*
* @borrows ResourceCache.getResourceList as getResourceList
* @borrows ResourceCache.updateTotalSize as updateTotalSize
diff --git a/libraries/model-networking/src/model-networking/ModelCacheScriptingInterface.h b/libraries/model-networking/src/model-networking/ModelCacheScriptingInterface.h
index cea2a6cd40..d83b853b01 100644
--- a/libraries/model-networking/src/model-networking/ModelCacheScriptingInterface.h
+++ b/libraries/model-networking/src/model-networking/ModelCacheScriptingInterface.h
@@ -37,6 +37,10 @@ class ModelCacheScriptingInterface : public ScriptableResourceCache, public Depe
* @property {number} numCached - Total number of cached resource. <em>Read-only.</em>
* @property {number} sizeTotal - Size in bytes of all resources. <em>Read-only.</em>
* @property {number} sizeCached - Size in bytes of all cached resources. <em>Read-only.</em>
+ * @property {number} numGlobalQueriesPending - Total number of global queries pending (across all resource cache managers).
+ * <em>Read-only.</em>
+ * @property {number} numGlobalQueriesLoading - Total number of global queries loading (across all resource cache managers).
+ * <em>Read-only.</em>
*
* @borrows ResourceCache.getResourceList as getResourceList
* @borrows ResourceCache.updateTotalSize as updateTotalSize
diff --git a/libraries/networking/src/ResourceCache.h b/libraries/networking/src/ResourceCache.h
index 4213d92fc0..9d08fd415a 100644
--- a/libraries/networking/src/ResourceCache.h
+++ b/libraries/networking/src/ResourceCache.h
@@ -318,9 +318,11 @@ class ScriptableResourceCache : public QObject {
Q_PROPERTY(size_t sizeCached READ getSizeCachedResources NOTIFY dirty)
/**jsdoc
- * @property {number} numGlobalQueriesPending - Total number of global queries pending (across all resource managers). <em>Read-only.</em>
- * @property {number} numGlobalQueriesLoading - Total number of global queries loading (across all resource managers). <em>Read-only.</em>
- */
+ * @property {number} numGlobalQueriesPending - Total number of global queries pending (across all resource cache managers).
+ * <em>Read-only.</em>
+ * @property {number} numGlobalQueriesLoading - Total number of global queries loading (across all resource cache managers).
+ * <em>Read-only.</em>
+ */
Q_PROPERTY(size_t numGlobalQueriesPending READ getNumGlobalQueriesPending NOTIFY dirty)
Q_PROPERTY(size_t numGlobalQueriesLoading READ getNumGlobalQueriesLoading NOTIFY dirty)
diff --git a/libraries/procedural/src/procedural/MaterialCacheScriptingInterface.h b/libraries/procedural/src/procedural/MaterialCacheScriptingInterface.h
index 3a13652aec..a1b2b1e01e 100644
--- a/libraries/procedural/src/procedural/MaterialCacheScriptingInterface.h
+++ b/libraries/procedural/src/procedural/MaterialCacheScriptingInterface.h
@@ -36,6 +36,10 @@ class MaterialCacheScriptingInterface : public ScriptableResourceCache, public D
* @property {number} numCached - Total number of cached resource. <em>Read-only.</em>
* @property {number} sizeTotal - Size in bytes of all resources. <em>Read-only.</em>
* @property {number} sizeCached - Size in bytes of all cached resources. <em>Read-only.</em>
+ * @property {number} numGlobalQueriesPending - Total number of global queries pending (across all resource cache managers).
+ * <em>Read-only.</em>
+ * @property {number} numGlobalQueriesLoading - Total number of global queries loading (across all resource cache managers).
+ * <em>Read-only.</em>
*
* @borrows ResourceCache.getResourceList as getResourceList
* @borrows ResourceCache.updateTotalSize as updateTotalSize
From fafb3dd30bddadd3119ca01baa4132638c8b0f14 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Tue, 26 Nov 2019 17:43:23 +1300
Subject: [PATCH 2/3] MaterialCache JSDoc
---
libraries/networking/src/ResourceCache.h | 8 ++++----
.../src/procedural/MaterialCacheScriptingInterface.h | 2 +-
tools/jsdoc/plugins/hifi.js | 1 +
3 files changed, 6 insertions(+), 5 deletions(-)
diff --git a/libraries/networking/src/ResourceCache.h b/libraries/networking/src/ResourceCache.h
index 9d08fd415a..ddc750664f 100644
--- a/libraries/networking/src/ResourceCache.h
+++ b/libraries/networking/src/ResourceCache.h
@@ -91,8 +91,8 @@ 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}.
+ * Information about a cached resource. Created by {@link AnimationCache.prefetch}, {@link MaterialCache.prefetch},
+ * {@link ModelCache.prefetch}, {@link SoundCache.prefetch}, or {@link TextureCache.prefetch}.
*
* @class ResourceObject
*
@@ -334,7 +334,7 @@ public:
* @function ResourceCache.getResourceList
* @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.
+ * // Replace AnimationCache with MaterialCache, ModelCache, SoundCache, or TextureCache as appropriate.
*
* var cachedResources = AnimationCache.getResourceList();
* print("Cached resources: " + JSON.stringify(cachedResources));
@@ -354,7 +354,7 @@ public:
* @param {string} url - The URL of the resource to prefetch.
* @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.
+ * // Replace AnimationCache with MaterialCache, 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";
diff --git a/libraries/procedural/src/procedural/MaterialCacheScriptingInterface.h b/libraries/procedural/src/procedural/MaterialCacheScriptingInterface.h
index a1b2b1e01e..2e0d319b7a 100644
--- a/libraries/procedural/src/procedural/MaterialCacheScriptingInterface.h
+++ b/libraries/procedural/src/procedural/MaterialCacheScriptingInterface.h
@@ -24,7 +24,7 @@ class MaterialCacheScriptingInterface : public ScriptableResourceCache, public D
// Properties are copied over from ResourceCache (see ResourceCache.h for reason).
/**jsdoc
- * The <code>TextureCache</code> API manages texture cache resources.
+ * The <code>MaterialCache</code> API manages material cache resources.
*
* @namespace MaterialCache
*
diff --git a/tools/jsdoc/plugins/hifi.js b/tools/jsdoc/plugins/hifi.js
index aa2b81c0a8..0da2a34c48 100644
--- a/tools/jsdoc/plugins/hifi.js
+++ b/tools/jsdoc/plugins/hifi.js
@@ -57,6 +57,7 @@ exports.handlers = {
'../../libraries/physics/src',
'../../libraries/platform/src/platform/backend',
'../../libraries/plugins/src/plugins',
+ '../../libraries/procedural/src/procedural',
'../../libraries/pointers/src',
'../../libraries/render-utils/src',
'../../libraries/script-engine/src',
From c998148589ee7c550a896aa217bc191820445cd2 Mon Sep 17 00:00:00 2001
From: David Rowe <david@ctrlaltstudio.com>
Date: Tue, 26 Nov 2019 17:43:41 +1300
Subject: [PATCH 3/3] Revise recent changes to Entities.Material JSDoc
---
.../procedural/ProceduralMaterialCache.cpp | 19 ++++++++++++-------
1 file changed, 12 insertions(+), 7 deletions(-)
diff --git a/libraries/procedural/src/procedural/ProceduralMaterialCache.cpp b/libraries/procedural/src/procedural/ProceduralMaterialCache.cpp
index b9611358e7..fcdfdfbea8 100644
--- a/libraries/procedural/src/procedural/ProceduralMaterialCache.cpp
+++ b/libraries/procedural/src/procedural/ProceduralMaterialCache.cpp
@@ -113,9 +113,9 @@ NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMater
/**jsdoc
* A material used in a {@link Entities.MaterialResource|MaterialResource}.
* @typedef {object} Entities.Material
+ * @property {string} name="" - A name for the material. Supported by all material models.
* @property {string} model="hifi_pbr" - Different material models support different properties and rendering modes.
* Supported models are: <code>"hifi_pbr"</code>, <code>"hifi_shader_simple"</code>.
- * @property {string} name="" - A name for the material. Supported by all material models.
* @property {ColorFloat|RGBS|string} emissive - The emissive color, i.e., the color that the material emits. A
* {@link ColorFloat} value is treated as sRGB and must have component values in the range <code>0.0</code> –
* <code>1.0</code>. A {@link RGBS} value can be either RGB or sRGB.
@@ -144,12 +144,17 @@ NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMater
* value for transparency.
* <code>"hifi_pbr"</code> model only.
* @property {number|string} opacityMapMode - The mode defining the interpretation of the opacity map. Values can be:
- * <code>"OPACITY_MAP_OPAQUE"</code> for ignoring the opacity map information.
- * <code>"OPACITY_MAP_MASK"</code> for using the opacity map as a mask, where only the texel greater than opacityCutoff are visible and rendered opaque.
- * <code>"OPACITY_MAP_BLEND"</code> for using the opacity map for alpha blending the material surface with the background.
+ * <ul>
+ * <li><code>"OPACITY_MAP_OPAQUE"</code> for ignoring the <code>opacityMap</code> 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>
* 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 Opacity map
- * when opacityMapMode is "OPACITY_MAP_MASK", range <code>0.0</code> – <code>1.0</code>.
+ * @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>1.0</code>.
* 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
* both.
@@ -179,7 +184,7 @@ NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMater
* Set to <code>"fallthrough"</code> to fall 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>.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
- * @property {string} lightmapParams - Parameters for controlling how lightMap is used.
+ * @property {string} lightmapParams - Parameters for controlling how <code>lightMap</code> is used.
* Set to <code>"fallthrough"</code> to fall through to the material below. <code>"hifi_pbr"</code> model only.
* <p><em>Currently not used.</em></p>
* @property {string} materialParams - Parameters for controlling the material projection and repetition.