From 70572c6b835cb7f800d423fceba5e196aa54b5ca Mon Sep 17 00:00:00 2001 From: David Rowe Date: Sun, 15 Dec 2019 14:14:30 +1300 Subject: [PATCH] Performance API JSDoc --- interface/src/RefreshRateManager.cpp | 18 +-- interface/src/RefreshRateManager.h | 30 +++++ .../scripting/PerformanceScriptingInterface.h | 108 ++++++++++++++++++ 3 files changed, 144 insertions(+), 12 deletions(-) diff --git a/interface/src/RefreshRateManager.cpp b/interface/src/RefreshRateManager.cpp index beb1363aac..90e084d3fd 100644 --- a/interface/src/RefreshRateManager.cpp +++ b/interface/src/RefreshRateManager.cpp @@ -19,7 +19,6 @@ static const int VR_TARGET_RATE = 90; /**jsdoc *

Refresh rate profile.

- * * * * @@ -32,15 +31,13 @@ static const int VR_TARGET_RATE = 90; *
Refresh Rate ProfileDescription
"Realtime"High refresh rate, even when Interface doesn't have focus or is minimized. * *
- * - * @typedef {string} RefreshRateProfile + * @typedef {string} RefreshRateProfileName */ static const std::array REFRESH_RATE_PROFILE_TO_STRING = { { "Eco", "Interactive", "Realtime" } }; /**jsdoc *

Interface states that affect the refresh rate.

- * * * * @@ -54,26 +51,23 @@ static const std::array * *
Refresh Rate RegimeDescription
"ShutDown"Interface is shutting down.
- * - * @typedef {string} RefreshRateRegime + * @typedef {string} RefreshRateRegimeName */ static const std::array REFRESH_RATE_REGIME_TO_STRING = { { "FocusActive", "FocusInactive", "Unfocus", "Minimized", "StartUp", "ShutDown" } }; /**jsdoc - *

Interface operates in different modes to provide different user experiences (UX).

- * + *

User experience (UX) modes.

* * * * * - * - * + * + * * *
UX ModeDescription
"Desktop"Desktop user experience mode.
"VR"VR user experience mode.
"Desktop"Desktop user experience.
"VR"VR user experience.
- * - * @typedef {string} UXMode + * @typedef {string} UXModeName */ static const std::array UX_MODE_TO_STRING = { { "Desktop", "VR" } }; diff --git a/interface/src/RefreshRateManager.h b/interface/src/RefreshRateManager.h index 567a515898..18fad392c9 100644 --- a/interface/src/RefreshRateManager.h +++ b/interface/src/RefreshRateManager.h @@ -31,6 +31,23 @@ public: }; static bool isValidRefreshRateProfile(RefreshRateProfile value) { return (value >= RefreshRateProfile::ECO && value <= RefreshRateProfile::REALTIME); } + /**jsdoc + *

Interface states that affect the refresh rate.

+ * + * + * + * + * + * + * + * + * + * + * + * + *
ValueNameDescription
0FOCUS_ACTIVEInterface has focus and the user is active or is in VR.
1FOCUS_INACTIVEInterface has focus and the user is inactive.
2UNFOCUSInterface doesn't have focus.
3MINIMIZEDInterface is minimized.
4STARTUPInterface is starting up.
5SHUTDOWNInterface is shutting down.
+ * @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 + *

User experience (UX) modes.

+ * + * + * + * + * + * + * + * + *
ValueNameDescription
0DESKTOPDesktop user experience.
1VRVR use experience.
+ * @typedef {number} UXMode + */ enum UXMode { DESKTOP = 0, VR, diff --git a/interface/src/scripting/PerformanceScriptingInterface.h b/interface/src/scripting/PerformanceScriptingInterface.h index 92d4273dfb..8a7e403e5d 100644 --- a/interface/src/scripting/PerformanceScriptingInterface.h +++ b/interface/src/scripting/PerformanceScriptingInterface.h @@ -18,6 +18,18 @@ #include "../RefreshRateManager.h" +/**jsdoc + * The Performance 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 + *

Graphics performance presets.

+ * + * + * + * + * + * + * + * + * + * + *
ValueNameDescription
0UNKNOWNCustom settings of world detail, rendering effects, and refresh + * rate.
1LOWLow world detail, no rendering effects, lo refresh rate.
2MIDMedium world detail, some rendering effects, medium refresh + * rate.
3HIGHMaximum world detail, all rendering effects, high refresh rate.
+ * @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 + *

Refresh rate profile.

+ * + * + * + * + * + * + * + * + * + *
ValueNameDescription
0ECOLow refresh rate, which is reduced when Interface doesn't have focus or + * is minimized.
1INTERACTIVEMedium refresh rate, which is reduced when Interface doesn't have + * focus or is minimized.
2REALTIMEHigh refresh rate, even when Interface doesn't have focus or is + * minimized.
+ * @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: