From 9e5cf5fe75edf12d10e9469e00fb01e24a14cba4 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Sat, 27 Jul 2019 11:50:07 +1200 Subject: [PATCH 1/4] Config.h is now exposed as the Workload API --- libraries/task/src/task/Config.h | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/libraries/task/src/task/Config.h b/libraries/task/src/task/Config.h index ab76bc5fba..75cecb5f18 100644 --- a/libraries/task/src/task/Config.h +++ b/libraries/task/src/task/Config.h @@ -109,14 +109,14 @@ public: virtual void setPresetList(const QJsonObject& object); /**jsdoc - * @function Render.toJSON + * @function Workload.toJSON * @returns {string} */ // This must be named toJSON to integrate with the global scripting JSON object Q_INVOKABLE QString toJSON() { return QJsonDocument(toJsonValue(*this).toObject()).toJson(QJsonDocument::Compact); } /**jsdoc - * @function Render.load + * @function Workload.load * @param {object} map */ Q_INVOKABLE void load(const QVariantMap& map) { qObjectFromJsonValue(QJsonObject::fromVariantMap(map), *this); emit loaded(); } @@ -130,25 +130,25 @@ public: // Describe the node graph data connections of the associated Job/Task /**jsdoc - * @function Render.isTask + * @function Workload.isTask * @returns {boolean} */ Q_INVOKABLE virtual bool isTask() const { return false; } /**jsdoc - * @function Render.getSubConfigs + * @function Workload.getSubConfigs * @returns {object[]} */ Q_INVOKABLE virtual QObjectList getSubConfigs() const { return QObjectList(); } /**jsdoc - * @function Render.getNumSubs + * @function Workload.getNumSubs * @returns {number} */ Q_INVOKABLE virtual int getNumSubs() const { return 0; } /**jsdoc - * @function Render.getSubConfig + * @function Workload.getSubConfig * @param {number} index * @returns {object} */ @@ -162,32 +162,32 @@ public: public slots: /**jsdoc - * @function Render.load + * @function Workload.load * @param {object} map */ void load(const QJsonObject& val) { qObjectFromJsonValue(val, *this); emit loaded(); } /**jsdoc - * @function Render.refresh + * @function Workload.refresh */ void refresh(); signals: /**jsdoc - * @function Render.loaded + * @function Workload.loaded * @returns {Signal} */ void loaded(); /**jsdoc - * @function Render.newStats + * @function Workload.newStats * @returns {Signal} */ void newStats(); /**jsdoc - * @function Render.dirtyEnabled + * @function Workload.dirtyEnabled * @returns {Signal} */ void dirtyEnabled(); @@ -202,7 +202,7 @@ public: /**jsdoc - * @namespace Render + * @namespace Workload * * @hifi-interface * @hifi-client-entity @@ -221,7 +221,7 @@ public: TaskConfig(bool enabled) : JobConfig(enabled) {} /**jsdoc - * @function Render.getConfig + * @function Workload.getConfig * @param {string} name * @returns {object} */ From 833bbf1cceef0aeab9025e7082b2a9069bf6dd39 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 30 Jul 2019 11:36:56 +1200 Subject: [PATCH 2/4] Render API JSDoc --- .../src/scripting/RenderScriptingInterface.h | 103 ++++++++++++------ 1 file changed, 72 insertions(+), 31 deletions(-) diff --git a/interface/src/scripting/RenderScriptingInterface.h b/interface/src/scripting/RenderScriptingInterface.h index 9b96448c9d..a514241126 100644 --- a/interface/src/scripting/RenderScriptingInterface.h +++ b/interface/src/scripting/RenderScriptingInterface.h @@ -15,13 +15,20 @@ #include "RenderForward.h" /**jsdoc - * The Render API allows you to configure the graphics engine + * The Render API enables you to configure the graphics engine. * * @namespace Render * * @hifi-interface * @hifi-client-entity * @hifi-avatar + * + * @property {Render.RenderMethod} renderMethod - The render method being used. + * @property {boolean} shadowsEnabled - true if shadows are enabled, false if they're disabled. + * @property {boolean} ambientOcclusionEnabled - {boolean} true if ambient occlusion is enabled, + * false if it's disabled. + * @property {boolean} antialiasingEnabled - true if anti-aliasing is enabled, false if it's disabled. + * @property {number} viewportResolutionScale - The view port resolution scale, > 0.0. */ class RenderScriptingInterface : public QObject { Q_OBJECT @@ -36,6 +43,21 @@ public: static RenderScriptingInterface* getInstance(); + /**jsdoc + *

The rendering method is specified by the following values:

+ * + * + * + * + * + * + * + * + *
ValueNameDescription
0DEFERREDMore complex rendering pipeline where lighting is applied to the + * scene as a whole after all objects have been rendered.
1FORWARDSimpler rendering pipeline where each object in the scene, in turn, + * is rendered and has lighting applied.
+ * @typedef {number} Render.RenderMethod + */ // RenderMethod enum type enum class RenderMethod { DEFERRED = render::Args::RenderMethod::DEFERRED, @@ -52,95 +74,114 @@ public: public slots: /**jsdoc - * Get a config for a job by name + * Gets the configuration for a rendering job by name. + *

Warning: For internal, debugging purposes. Subject to change.

* @function Render.getConfig - * @param {string} name - Can be: - * - : Search for the first job named job_name traversing the the sub graph of task and jobs (from this task as root) - * - .[.]: Allows you to first look for the parent_name job (from this task as root) and then search from there for the - * optional sub_parent_names and finally from there looking for the job_name (assuming every job in the path is found) - * @returns {object} The sub job config. + * @param {string} name - The name of the rendering job. + * @returns {object} The configuration for the rendering job. */ QObject* getConfig(const QString& name) { return qApp->getRenderEngine()->getConfiguration()->getConfig(name); } + /**jsdoc - * Gets the current render method + * Gets the render method being used. * @function Render.getRenderMethod - * @returns {number} "DEFERRED" or "FORWARD" + * @returns {Render.RenderMethod} The render method being used. + * @example Report the current render method. + * var renderMethod = Render.getRenderMethod(); + * print("Current render method: " + Render.getRenderMethodNames()[renderMethod]); */ RenderMethod getRenderMethod() const; /**jsdoc - * Sets the current render method + * Sets the render method to use. * @function Render.setRenderMethod - * @param {number} renderMethod - "DEFERRED" or "FORWARD" + * @param {Render.RenderMethod} renderMethod - The render method to use. */ void setRenderMethod(RenderMethod renderMethod); /**jsdoc - * Gets the possible enum names of the RenderMethod type - * @function Render.getRenderMethodNames - * @returns [string] [ "DEFERRED", "FORWARD" ] - */ + * Gets the names of the possible render methods, per {@link Render.RenderMethod}. + * @function Render.getRenderMethodNames + * @returns {string[]} The names of the possible render methods. + * @example Report the names of the possible render methods. + * var renderMethods = Render.getRenderMethodNames(); + * print("Render methods:"); + * for (var i = 0; i < renderMethods.length; i++) { + * print("- " + renderMethods[i]); + * } + */ QStringList getRenderMethodNames() const; /**jsdoc - * Whether or not shadows are enabled + * Gets whether or not shadows are enabled. * @function Render.getShadowsEnabled - * @returns {bool} true if shadows are enabled, otherwise false + * @returns {boolean} true if shadows are enabled, false if they're disabled. */ bool getShadowsEnabled() const; /**jsdoc - * Enables or disables shadows + * Sets whether or not shadows are enabled. * @function Render.setShadowsEnabled - * @param {bool} enabled - true to enable shadows, false to disable them + * @param {boolean} enabled - true to enable shadows, false to disable. */ void setShadowsEnabled(bool enabled); /**jsdoc - * Whether or not ambient occlusion is enabled + * Gets whether or not ambient occlusion is enabled. * @function Render.getAmbientOcclusionEnabled - * @returns {bool} true if ambient occlusion is enabled, otherwise false + * @returns {boolean} true if ambient occlusion is enabled, false if it's disabled. */ bool getAmbientOcclusionEnabled() const; /**jsdoc - * Enables or disables ambient occlusion + * Sets whether or not ambient occlusion is enabled. * @function Render.setAmbientOcclusionEnabled - * @param {bool} enabled - true to enable ambient occlusion, false to disable it + * @param {boolean} enabled - true to enable ambient occlusion, false to disable. */ void setAmbientOcclusionEnabled(bool enabled); /**jsdoc - * Whether or not anti-aliasing is enabled + * Gets whether or not anti-aliasing is enabled. * @function Render.getAntialiasingEnabled - * @returns {bool} true if anti-aliasing is enabled, otherwise false + * @returns {boolean} true if anti-aliasing is enabled, false if it's disabled. */ bool getAntialiasingEnabled() const; /**jsdoc - * Enables or disables anti-aliasing + * Sets whether or not anti-aliasing is enabled. * @function Render.setAntialiasingEnabled - * @param {bool} enabled - true to enable anti-aliasing, false to disable it + * @param {boolean} enabled - true to enable anti-aliasing, false to disable. */ void setAntialiasingEnabled(bool enabled); /**jsdoc - * Gets the current viewport resolution scale + * Gets the view port resolution scale. * @function Render.getViewportResolutionScale - * @returns {number} + * @returns {number} The view port resolution scale, > 0.0. */ float getViewportResolutionScale() const; /**jsdoc - * Sets the current viewport resolution scale + * Sets the view port resolution scale. * @function Render.setViewportResolutionScale - * @param {number} resolutionScale - between epsilon and 1.0 + * @param {number} resolutionScale - The view port resolution scale to set, > 0.0. */ void setViewportResolutionScale(float resolutionScale); signals: + + /**jsdoc + * Triggered when one of the Render API's properties changes. + * @function Render.settingsChanged + * @returns {Signal} + * @example Report when a render setting changes. + * Render.settingsChanged.connect(function () { + * print("Render setting changed"); + * }); + * // Toggle Developer > Render > Shadows or similar to trigger. + */ void settingsChanged(); private: From e5c58d5ba58a2299bf082987865191768ce7b28d Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 30 Jul 2019 11:37:20 +1200 Subject: [PATCH 3/4] Fix JSDoc typo noticed in passing --- libraries/avatars/src/AvatarData.h | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index 3c8e2d6fcc..550b8bb2ac 100755 --- a/libraries/avatars/src/AvatarData.h +++ b/libraries/avatars/src/AvatarData.h @@ -117,8 +117,7 @@ const int COLLIDE_WITH_OTHER_AVATARS = 11; // 12th bit const int HAS_HERO_PRIORITY = 12; // 13th bit (be scared) /**jsdoc - *

The pointing state of the hands is specified by the following values: -

+ *

The pointing state of the hands is specified by the following values:

* * * From f97417932c6dfd12399cbeb48e63cd02e39348ad Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 6 Aug 2019 08:08:08 +1200 Subject: [PATCH 4/4] Fix typo --- interface/src/scripting/RenderScriptingInterface.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/interface/src/scripting/RenderScriptingInterface.h b/interface/src/scripting/RenderScriptingInterface.h index a514241126..1c2443144a 100644 --- a/interface/src/scripting/RenderScriptingInterface.h +++ b/interface/src/scripting/RenderScriptingInterface.h @@ -25,8 +25,8 @@ * * @property {Render.RenderMethod} renderMethod - The render method being used. * @property {boolean} shadowsEnabled - true if shadows are enabled, false if they're disabled. - * @property {boolean} ambientOcclusionEnabled - {boolean} true if ambient occlusion is enabled, - * false if it's disabled. + * @property {boolean} ambientOcclusionEnabled - true if ambient occlusion is enabled, false if it's + * disabled. * @property {boolean} antialiasingEnabled - true if anti-aliasing is enabled, false if it's disabled. * @property {number} viewportResolutionScale - The view port resolution scale, > 0.0. */
ValueDescription