From 833bbf1cceef0aeab9025e7082b2a9069bf6dd39 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Tue, 30 Jul 2019 11:36:56 +1200 Subject: [PATCH] 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: