Merge pull request #16576 from ctrlaltdavid/DOC-157

DOC-157: LODManager and Performance JSDoc
This commit is contained in:
Brad Hefta-Gaub 2019-12-15 11:22:36 -08:00 committed by GitHub
commit 022e1c3db3
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 253 additions and 40 deletions

View file

@ -66,16 +66,62 @@ class AABox;
/**jsdoc
* The LOD class manages your Level of Detail functions within Interface.
* The <code>LODManager</code> 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 <em>Read-only.</em>
* @property {number} engineRunTime <em>Read-only.</em>
* @property {number} gpuTime <em>Read-only.</em>
* @property {LODManager.WorldDetailQuality} worldDetailQuality - The quality of the rendered world detail.
* <p>Setting this value updates the current desktop or HMD target LOD FPS.</p>
* @property {number} lodQualityLevel - <em>Not used.</em>
* <p class="important">Deprecated: This property is deprecated and will be removed.</p>
* @property {boolean} automaticLODAdjust - <code>true</code> to automatically adjust the LOD, <code>false</code> to manually
* adjust it.
*
* @property {number} engineRunTime - The time spent in the "render" thread to produce the most recent frame, in ms.
* <em>Read-only.</em>
* @property {number} batchTime - The time spent in the "present" thread processing the batches of the most recent frame, in ms.
* <em>Read-only.</em>
* @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.
* <em>Read-only.</em>
* @property {number} gpuTime - The time spent in the GPU executing the most recent frame, in ms.
* <em>Read-only.</em>
*
* @property {number} nowRenderTime - The current, instantaneous time spend to produce frames, in ms. This is the worst of
* <code>engineRunTime</code>, <code>batchTime</code>, <code>presentTime</code>, and <code>gpuTime</code>.
* <em>Read-only.</em>
* @property {number} nowRenderFPS - The current, instantaneous frame rate, in Hz.
* <em>Read-only.</em>
*
* @property {number} smoothScale - The amount of smoothing applied to calculate <code>smoothRenderTime</code> and
* <code>smoothRenderFPS</code>.
* @property {number} smoothRenderTime - The average time spend to produce frames, in ms.
* <em>Read-only.</em>
* @property {number} smoothRenderFPS - The average frame rate, in Hz.
* <em>Read-only.</em>
*
* @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.
* <em>Read-only.</em>
* @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 - <em>Not used.</em>
* @property {number} pidKi - <em>Not used.</em>
* @property {number} pidKd - <em>Not used.</em>
* @property {number} pidKv - <em>Not used.</em>
* @property {number} pidOp - <em>Not used.</em> <em>Read-only.</em>
* @property {number} pidOi - <em>Not used.</em> <em>Read-only.</em>
* @property {number} pidOd - <em>Not used.</em> <em>Read-only.</em>
* @property {number} pidO - <em>Not used.</em> <em>Read-only.</em>
*/
class LODManager : public QObject, public Dependency {
Q_OBJECT
@ -117,83 +163,96 @@ 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 - <code>true</code> to automatically adjust the LOD, <code>false</code> 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} <code>true</code> if the LOD is being automatically adjusted, <code>false</code> if it is being
* manually adjusted.
*/
Q_INVOKABLE bool getAutomaticLODAdjust() const { return _automaticLODAdjust; }
/**jsdoc
* Sets the target desktop LOD FPS.
* @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 <caption>Report the current level of detail rendered.</caption>
* 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 <code>lodAngleDeg</code> 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 <code>lodAngleDeg</code> 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 +308,41 @@ public:
signals:
/**jsdoc
* <em>Not triggered.</em>
* @function LODManager.LODIncreased
* @returns {Signal}
* @deprecated This signal is deprecated and will be removed.
*/
void LODIncreased();
/**jsdoc
* <em>Not triggered.</em>
* @function LODManager.LODDecreased
* @returns {Signal}
* @deprecated This signal is deprecated and will be removed.
*/
void LODDecreased();
/**jsdoc
* Triggered when whether or not the LOD is being automatically adjusted changes.
* @function LODManager.autoLODChanged
* @returns {Signal}
*/
void autoLODChanged();
/**jsdoc
* Triggered when the <code>lodQualityLevel</code> 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:

View file

@ -19,10 +19,9 @@ static const int VR_TARGET_RATE = 90;
/**jsdoc
* <p>Refresh rate profile.</p>
*
* <table>
* <thead>
* <tr><th>Refresh Rate Profile</th><th>Description</th></tr>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>"Eco"</code></td><td>Low refresh rate, which is reduced when Interface doesn't have focus or is
@ -32,18 +31,16 @@ static const int VR_TARGET_RATE = 90;
* <tr><td><code>"Realtime"</code></td><td>High refresh rate, even when Interface doesn't have focus or is minimized.
* </tbody>
* </table>
*
* @typedef {string} RefreshRateProfile
* @typedef {string} RefreshRateProfileName
*/
static const std::array<std::string, RefreshRateManager::RefreshRateProfile::PROFILE_NUM> REFRESH_RATE_PROFILE_TO_STRING =
{ { "Eco", "Interactive", "Realtime" } };
/**jsdoc
* <p>Interface states that affect the refresh rate.</p>
*
* <table>
* <thead>
* <tr><th>Refresh Rate Regime</th><th>Description</th></tr>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>"FocusActive"</code></td><td>Interface has focus and the user is active or is in VR.</td></tr>
@ -54,26 +51,23 @@ static const std::array<std::string, RefreshRateManager::RefreshRateProfile::PRO
* <tr><td><code>"ShutDown"</code></td><td>Interface is shutting down.</td></tr>
* </tbody>
* </table>
*
* @typedef {string} RefreshRateRegime
* @typedef {string} RefreshRateRegimeName
*/
static const std::array<std::string, RefreshRateManager::RefreshRateRegime::REGIME_NUM> REFRESH_RATE_REGIME_TO_STRING =
{ { "FocusActive", "FocusInactive", "Unfocus", "Minimized", "StartUp", "ShutDown" } };
/**jsdoc
* <p>Interface operates in different modes to provide different user experiences (UX).</p>
*
* <p>User experience (UX) modes.</p>
* <table>
* <thead>
* <tr><th>UX Mode</th><th>Description</th></tr>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>"Desktop"</code></td><td>Desktop user experience mode.</td></tr>
* <tr><td><code>"VR"</code></td><td>VR user experience mode.</td></tr>
* <tr><td><code>"Desktop"</code></td><td>Desktop user experience.</td></tr>
* <tr><td><code>"VR"</code></td><td>VR user experience.</td></tr>
* </tbody>
* </table>
*
* @typedef {string} UXMode
* @typedef {string} UXModeName
*/
static const std::array<std::string, RefreshRateManager::UXMode::UX_NUM> UX_MODE_TO_STRING =
{ { "Desktop", "VR" } };

View file

@ -31,6 +31,23 @@ public:
};
static bool isValidRefreshRateProfile(RefreshRateProfile value) { return (value >= RefreshRateProfile::ECO && value <= RefreshRateProfile::REALTIME); }
/**jsdoc
* <p>Interface states that affect the refresh rate.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Name</th><th>Description</th>
* </thead>
* <tbody>
* <tr><td><code>0</code></td><td>FOCUS_ACTIVE</td><td>Interface has focus and the user is active or is in VR.</td></tr>
* <tr><td><code>1</code></td><td>FOCUS_INACTIVE</td><td>Interface has focus and the user is inactive.</td></tr>
* <tr><td><code>2</code></td><td>UNFOCUS</td><td>Interface doesn't have focus.</td></tr>
* <tr><td><code>3</code></td><td>MINIMIZED</td><td>Interface is minimized.</td></tr>
* <tr><td><code>4</code></td><td>STARTUP</td><td>Interface is starting up.</td></tr>
* <tr><td><code>5</code></td><td>SHUTDOWN</td><td>Interface is shutting down.</td></tr>
* </tbody>
* </table>
* @typedef {number} RefreshRateRegime
*/
enum RefreshRateRegime {
FOCUS_ACTIVE = 0,
FOCUS_INACTIVE,
@ -42,6 +59,19 @@ public:
};
static bool isValidRefreshRateRegime(RefreshRateRegime value) { return (value >= RefreshRateRegime::FOCUS_ACTIVE && value <= RefreshRateRegime::SHUTDOWN); }
/**jsdoc
* <p>User experience (UX) modes.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Name</th><th>Description</th>
* </thead>
* <tbody>
* <tr><td><code>0</code></td><td>DESKTOP</td><td>Desktop user experience.</td></tr>
* <tr><td><code>1</code></td><td>VR</td><td>VR use experience.</td></tr>
* </tbody>
* </table>
* @typedef {number} UXMode
*/
enum UXMode {
DESKTOP = 0,
VR,

View file

@ -18,6 +18,18 @@
#include "../RefreshRateManager.h"
/**jsdoc
* The <code>Performance</code> API provides control and information on graphics performance settings.
*
* @namespace Performance
*
* @hifi-interface
* @hifi-client-entity
* @hifi-avatar
*
* @property {Performance.PerformancePreset} performancePreset - The current graphics performance preset.
* @property {Performance.RefreshRateProfile} refreshRateProfile - The current refresh rate profile.
*/
class PerformanceScriptingInterface : public QObject {
Q_OBJECT
Q_PROPERTY(PerformancePreset performancePreset READ getPerformancePreset WRITE setPerformancePreset NOTIFY settingsChanged)
@ -25,6 +37,23 @@ class PerformanceScriptingInterface : public QObject {
public:
/**jsdoc
* <p>Graphics performance presets.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Name</th><th>Description</th>
* </thead>
* <tbody>
* <tr><td><code>0</code></td><td>UNKNOWN</td><td>Custom settings of world detail, rendering effects, and refresh
* rate.</td></tr>
* <tr><td><code>1</code></td><td>LOW</td><td>Low world detail, no rendering effects, lo refresh rate.</td></tr>
* <tr><td><code>2</code></td><td>MID</td><td>Medium world detail, some rendering effects, medium refresh
* rate.</td></tr>
* <tr><td><code>3</code></td><td>HIGH</td><td>Maximum world detail, all rendering effects, high refresh rate.</td></tr>
* </tbody>
* </table>
* @typedef {number} Performance.PerformancePreset
*/
// PerformanceManager PerformancePreset tri state level enums
enum PerformancePreset {
UNKNOWN = PerformanceManager::PerformancePreset::UNKNOWN,
@ -34,6 +63,23 @@ public:
};
Q_ENUM(PerformancePreset)
/**jsdoc
* <p>Refresh rate profile.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Name</th><th>Description</th>
* </thead>
* <tbody>
* <tr><td><code>0</code></td><td>ECO</td><td>Low refresh rate, which is reduced when Interface doesn't have focus or
* is minimized.</td></tr>
* <tr><td><code>1</code></td><td>INTERACTIVE</td><td>Medium refresh rate, which is reduced when Interface doesn't have
* focus or is minimized.</td></tr>
* <tr><td><code>2</code></td><td>REALTIME</td><td>High refresh rate, even when Interface doesn't have focus or is
* minimized. </td></tr>
* </tbody>
* </table>
* @typedef {number} Performance.RefreshRateProfile
*/
// Must match RefreshRateManager enums
enum RefreshRateProfile {
ECO = RefreshRateManager::RefreshRateProfile::ECO,
@ -47,19 +93,81 @@ public:
public slots:
/**jsdoc
* Sets graphics performance to a preset.
* @function Performance.setPerformancePreset
* @param {Performance.PerformancePreset} performancePreset - The graphics performance preset to to use.
*/
void setPerformancePreset(PerformancePreset performancePreset);
/**jsdoc
* Gets the current graphics performance preset in use.
* @function Performance.getPerformancePreset
* @returns {Performance.PerformancePreset} The current graphics performance preset in use.
*/
PerformancePreset getPerformancePreset() const;
/**jsdoc
* Gets the names of the graphics performance presets.
* @function Performance.getPerformancePresetNames
* @returns {string[]} The names of the graphics performance presets. The array index values correspond to
* {@link Performance.PerformancePreset} values.
*/
QStringList getPerformancePresetNames() const;
/**jsdoc
* Sets the curfrent refresh rate profile.
* @function Performance.setRefreshRateProfile
* @param {Performance.RefreshRateProfile} refreshRateProfile - The refresh rate profile.
*/
void setRefreshRateProfile(RefreshRateProfile refreshRateProfile);
/**jsdoc
* Gets the current refresh rate profile in use.
* @function Performance.getRefreshRateProfile
* @returns {Performance.RefreshRateProfile} The refresh rate profile.
*/
RefreshRateProfile getRefreshRateProfile() const;
/**jsdoc
* Gets the names of the refresh rate profiles.
* @function Performance.getRefreshRateProfileNames
* @returns {string[]} The names of the refresh rate profiles. The array index values correspond to
* {@link Performance.RefreshRateProfile} values.
*/
QStringList getRefreshRateProfileNames() const;
/**jsdoc
* Gets the current target refresh rate, in Hz, per the current refresh rate profile and refresh rate regime if in desktop
* mode; a higher rate if in VR mode.
* @function Performance.getActiveRefreshRate
* @returns {number} The current target refresh rate, in Hz.
*/
int getActiveRefreshRate() const;
/**jsdoc
* Gets the current user experience mode.
* @function Performance.getUXMode
* @returns {UXMode} The current user experience mode.
*/
RefreshRateManager::UXMode getUXMode() const;
/**jsdoc
* Gets the current refresh rate regime that's in effect.
* @function Performance.getRefreshRateRegime
* @returns {RefreshRateRegime} The current refresh rate regime.
*/
RefreshRateManager::RefreshRateRegime getRefreshRateRegime() const;
signals:
/**jsdoc
* Triggered when the performance preset or refresh rate profile is changed.
* @function Performance.settingsChanged
* @returns {Signal}
*/
void settingsChanged();
private:

View file

@ -72,14 +72,14 @@ private: \
* @property {number} gameLoopRate - The rate at which the game loop is running, in Hz.
* <em>Read-only.</em>
* @property {number} refreshRateTarget - The current refresh rate target per the current <code>refreshRateMode</code> and
* <code>refreshRateRegime</code> if in desktop mode; a higher rate if in VR mode.
* @property {number} refreshRateTarget - The current target refresh rate, in Hz, per the current <code>refreshRateMode</code>
* and <code>refreshRateRegime</code> if in desktop mode; a higher rate if in VR mode.
* <em>Read-only.</em>
* @property {RefreshRateProfile} refreshRateMode - The current refresh rate profile.
* @property {RefreshRateProfileName} refreshRateMode - The current refresh rate profile.
* <em>Read-only.</em>
* @property {RefreshRateRegime} refreshRateRegime - The current refresh rate regime.
* @property {RefreshRateRegimeName} refreshRateRegime - The current refresh rate regime.
* <em>Read-only.</em>
* @property {UXMode} uxMode - The user experience (UX) mode that Interface is running in.
* @property {UXModeName} uxMode - The user experience (UX) mode that Interface is running in.
* <em>Read-only.</em>
* @property {number} avatarCount - The number of avatars in the domain other than the client's.
* <em>Read-only.</em>