From f1c23b8072b2808b6be39698bb58b36d1a6c6d0b Mon Sep 17 00:00:00 2001 From: David Rowe Date: Sun, 15 Dec 2019 14:14:09 +1300 Subject: [PATCH] LODManager API JSDoc --- interface/src/LODManager.h | 123 +++++++++++++++++++++++++++++++------ 1 file changed, 103 insertions(+), 20 deletions(-) diff --git a/interface/src/LODManager.h b/interface/src/LODManager.h index 4708deb61b..36312d16e5 100644 --- a/interface/src/LODManager.h +++ b/interface/src/LODManager.h @@ -66,16 +66,62 @@ class AABox; /**jsdoc - * The LOD class manages your Level of Detail functions within Interface. + * The LODManager API manages the Level of Detail displayed in Interface. If the LOD is being automatically + * adjusted, the LOD is decreased if the measured frame rate is lower than the target FPS, and increased if the measured frame + * rate is greater than the target FPS. + * * @namespace LODManager * * @hifi-interface * @hifi-client-entity * @hifi-avatar * - * @property {number} presentTime Read-only. - * @property {number} engineRunTime Read-only. - * @property {number} gpuTime Read-only. + * @property {LODManager.WorldDetailQuality} worldDetailQuality - The quality of the rendered world detail. + *

Setting this value updates the current desktop or HMD target LOD FPS.

+ * @property {number} lodQualityLevel - Not used. + *

Deprecated: This property is deprecated and will be removed.

+ * @property {boolean} automaticLODAdjust - true to automatically adjust the LOD, false to manually + * adjust it. + * + * @property {number} engineRunTime - The time spent in the "render" thread to produce the most recent frame, in ms. + * Read-only. + * @property {number} batchTime - The time spent in the "present" thread processing the batches of the most recent frame, in ms. + * Read-only. + * @property {number} presentTime - The time spent in the "present" thread between the last buffer swap, i.e., the total time + * to submit the most recent frame, in ms. + * Read-only. + * @property {number} gpuTime - The time spent in the GPU executing the most recent frame, in ms. + * Read-only. + * + * @property {number} nowRenderTime - The current, instantaneous time spend to produce frames, in ms. This is the worst of + * engineRunTime, batchTime, presentTime, and gpuTime. + * Read-only. + * @property {number} nowRenderFPS - The current, instantaneous frame rate, in Hz. + * Read-only. + * + * @property {number} smoothScale - The amount of smoothing applied to calculate smoothRenderTime and + * smoothRenderFPS. + * @property {number} smoothRenderTime - The average time spend to produce frames, in ms. + * Read-only. + * @property {number} smoothRenderFPS - The average frame rate, in Hz. + * Read-only. + * + * @property {number} lodTargetFPS - The target LOD FPS per the current desktop or HMD display mode, capped by the target + * refresh rate set by the {@link Performance} API. + * Read-only. + + * @property {number} lodAngleDeg - The minimum angular dimension (relative to the camera position) of an entity in order for + * it to be rendered, in degrees. The angular dimension is calculated as a sphere of radius half the diagonal of the + * entity's AA box. + * + * @property {number} pidKp - Not used. + * @property {number} pidKi - Not used. + * @property {number} pidKd - Not used. + * @property {number} pidKv - Not used. + * @property {number} pidOp - Not used. Read-only. + * @property {number} pidOi - Not used. Read-only. + * @property {number} pidOd - Not used. Read-only. + * @property {number} pidO - Not used. Read-only. */ class LODManager : public QObject, public Dependency { Q_OBJECT @@ -117,83 +163,97 @@ class LODManager : public QObject, public Dependency { public: /**jsdoc + * Sets whether the LOD should be automatically adjusted. * @function LODManager.setAutomaticLODAdjust - * @param {boolean} value + * @param {boolean} value - true to automatically adjust the LOD, false to manually adjust it. */ Q_INVOKABLE void setAutomaticLODAdjust(bool value); /**jsdoc + * Gets whether the LOD is being automatically adjusted. * @function LODManager.getAutomaticLODAdjust - * @returns {boolean} + * @returns {boolean} true if the LOD is being automatically adjusted, false if it is being + * manually adjusted. */ Q_INVOKABLE bool getAutomaticLODAdjust() const { return _automaticLODAdjust; } /**jsdoc + * Sets the target desktop LOD FPS. + *

Note: Called by {@link LODManager. * @function LODManager.setDesktopLODTargetFPS - * @param {number} value + * @param {number} value - The target desktop LOD FPS, in Hz. */ Q_INVOKABLE void setDesktopLODTargetFPS(float value); /**jsdoc + * Gets the target desktop LOD FPS. * @function LODManager.getDesktopLODTargetFPS - * @returns {number} + * @returns {number} The target desktop LOD FPS, in Hz. */ Q_INVOKABLE float getDesktopLODTargetFPS() const; /**jsdoc + * Sets the target HMD LOD FPS. * @function LODManager.setHMDLODTargetFPS - * @param {number} value + * @param {number} value - The target HMD LOD FPS, in Hz. */ Q_INVOKABLE void setHMDLODTargetFPS(float value); /**jsdoc + * Gets the target HMD LOD FPS. + * The target FPS in HMD mode. The LOD is adjusted to ... * @function LODManager.getHMDLODTargetFPS - * @returns {number} + * @returns {number} The target HMD LOD FPS, in Hz. */ Q_INVOKABLE float getHMDLODTargetFPS() const; // User Tweakable LOD Items + /**jsdoc + * Gets a text description of the current level of detail rendered. * @function LODManager.getLODFeedbackText - * @returns {string} + * @returns {string} A text description of the current level of detail rendered. + * @example Report the current level of detail rendered. + * print("You can currently see: " + LODManager.getLODFeedbackText()); */ Q_INVOKABLE QString getLODFeedbackText(); /**jsdoc * @function LODManager.setOctreeSizeScale - * @param {number} sizeScale - * @deprecated This function is deprecated and will be removed. Use the {@link LODManager.lodAngleDeg} property instead. + * @param {number} sizeScale - The octree size scale. + * @deprecated This function is deprecated and will be removed. Use the lodAngleDeg property instead. */ Q_INVOKABLE void setOctreeSizeScale(float sizeScale); /**jsdoc * @function LODManager.getOctreeSizeScale - * @returns {number} - * @deprecated This function is deprecated and will be removed. Use the {@link LODManager.lodAngleDeg} property instead. + * @returns {number} The octree size scale. + * @deprecated This function is deprecated and will be removed. Use the lodAngleDeg property instead. */ Q_INVOKABLE float getOctreeSizeScale() const; /**jsdoc * @function LODManager.setBoundaryLevelAdjust - * @param {number} boundaryLevelAdjust + * @param {number} boundaryLevelAdjust - The boundary level adjust factor. * @deprecated This function is deprecated and will be removed. */ Q_INVOKABLE void setBoundaryLevelAdjust(int boundaryLevelAdjust); /**jsdoc * @function LODManager.getBoundaryLevelAdjust - * @returns {number} + * @returns {number} The boundary level adjust factor. * @deprecated This function is deprecated and will be removed. */ Q_INVOKABLE int getBoundaryLevelAdjust() const { return _boundaryLevelAdjust; } /**jsdoc - * @function LODManager.getLODTargetFPS - * @returns {number} - */ + * The target LOD FPS per the current desktop or HMD display mode, capped by the target refresh rate. + * @function LODManager.getLODTargetFPS + * @returns {number} The target LOD FPS, in Hz. + */ Q_INVOKABLE float getLODTargetFPS() const; @@ -249,19 +309,42 @@ public: signals: /**jsdoc + * Not triggered. * @function LODManager.LODIncreased * @returns {Signal} + * @deprecated This signal is deprecated and will be removed. */ void LODIncreased(); /**jsdoc + * Not triggered. * @function LODManager.LODDecreased * @returns {Signal} + * @deprecated This signal is deprecated and will be removed. */ void LODDecreased(); + /**jsdoc + * Triggered when whether the LOD is being automatically adjusted changes. + * Use {@link LODManager.getAutomaticLODAdjust|getAutomaticLODAdjust} to get whether the LOD is being automatically adjusted. + * @function LODManager.autoLODChanged + * @returns {Signal} + */ void autoLODChanged(); + + /**jsdoc + * Triggered when the lodQualityLevel property value changes. + * @function LODManager.lodQualityLevelChanged + * @returns {Signal} + * @deprecated This signal is deprecated and will be removed. + */ void lodQualityLevelChanged(); + + /**jsdoc + * Triggered when the world detail quality changes. + * @function LODManager.worldDetailQualityChanged + * @returns {Signal} + */ void worldDetailQualityChanged(); private: