diff --git a/assignment-client/src/avatars/ScriptableAvatar.h b/assignment-client/src/avatars/ScriptableAvatar.h index 3ef908bedb..fc796b418f 100644 --- a/assignment-client/src/avatars/ScriptableAvatar.h +++ b/assignment-client/src/avatars/ScriptableAvatar.h @@ -97,8 +97,10 @@ public: /**jsdoc * Starts playing an animation on the avatar. * @function Avatar.startAnimation - * @param {string} url - The animation file's URL. Animation files need to be in the FBX format but only need to contain - * the avatar skeleton and animation data. + * @param {string} url - The animation file's URL. Animation files need to be in glTF or FBX format but only need to + * contain the avatar skeleton and animation data. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs + * respectively). + *

Warning: glTF animations currently do not always animate correctly.

* @param {number} [fps=30] - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. * @param {number} [priority=1] - Not used. * @param {boolean} [loop=false] - true if the animation should loop, false if it shouldn't. diff --git a/interface/resources/qml/hifi/simplifiedUI/settingsApp/about/About.qml b/interface/resources/qml/hifi/simplifiedUI/settingsApp/about/About.qml index d562aae70d..632f137339 100644 --- a/interface/resources/qml/hifi/simplifiedUI/settingsApp/about/About.qml +++ b/interface/resources/qml/hifi/simplifiedUI/settingsApp/about/About.qml @@ -184,7 +184,7 @@ Flickable { wrapMode: Text.Wrap Component.onCompleted: { - var gpu = JSON.parse(PlatformInfo.getGPU(0)); + var gpu = JSON.parse(PlatformInfo.getGPU(PlatformInfo.getMasterGPU())); var gpuModel = gpu.model; if (gpuModel.length === 0) { gpuModel = "Unknown"; @@ -313,7 +313,7 @@ Flickable { textToCopy += "# CPU Cores: " + PlatformInfo.getNumLogicalCores() + "\n"; textToCopy += "RAM: " + PlatformInfo.getTotalSystemMemoryMB() + " MB\n"; - var gpu = JSON.parse(PlatformInfo.getGPU(0)); + var gpu = JSON.parse(PlatformInfo.getGPU(PlatformInfo.getMasterGPU())); var gpuModel = gpu.model; if (gpuModel.length === 0) { gpuModel = "Unknown"; diff --git a/interface/src/avatar/MyAvatar.h b/interface/src/avatar/MyAvatar.h index 73b6ad08ea..ad45df892b 100644 --- a/interface/src/avatar/MyAvatar.h +++ b/interface/src/avatar/MyAvatar.h @@ -609,8 +609,10 @@ public: * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see * Avatar Standards.

* @function MyAvatar.overrideAnimation - * @param {string} url - The URL to the animation file. Animation files need to be FBX format, but only need to contain the - * avatar skeleton and animation data. + * @param {string} url - The URL to the animation file. Animation files may be in glTF or FBX format, but only need to + * contain the avatar skeleton and animation data. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs + * respectively). + *

Warning: glTF animations currently do not always animate correctly.

* @param {number} fps - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. * @param {boolean} loop - true if the animation should loop, false if it shouldn't. * @param {number} firstFrame - The frame to start the animation at. @@ -630,8 +632,10 @@ public: * Use {@link MyAvatar.restoreHandAnimation} to restore the default poses. * @function MyAvatar.overrideHandAnimation * @param isLeft {boolean} true to override the left hand, false to override the right hand. - * @param {string} url - The URL of the animation file. Animation files need to be FBX format, but only need to contain the - * avatar skeleton and animation data. + * @param {string} url - The URL of the animation file. Animation files need to be in glTF or FBX format, but only need to + * contain the avatar skeleton and animation data. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs + * respectively). + *

Warning: glTF animations currently do not always animate correctly.

* @param {number} fps - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. * @param {boolean} loop - true if the animation should loop, false if it shouldn't. * @param {number} firstFrame - The frame to start the animation at. @@ -702,19 +706,22 @@ public: *

Each avatar has an avatar-animation.json file that defines a set of animation roles. Animation roles map to easily * understandable actions that the avatar can perform, such as "idleStand", "idleTalk", or * "walkFwd". To get the full list of roles, use {@ link MyAvatar.getAnimationRoles}. - * For each role, the avatar-animation.json defines when the animation is used, the animation clip (FBX) used, and how - * animations are blended together with procedural data (such as look at vectors, hand sensors etc.). - * overrideRoleAnimation() is used to change the animation clip (FBX) associated with a specified animation - * role. To end the role animation and restore the default, use {@link MyAvatar.restoreRoleAnimation}.

- *

Note: Hand roles only affect the hand. Other 'main' roles, like 'idleStand', 'idleTalk', 'takeoffStand' are full body.

+ * For each role, the avatar-animation.json defines when the animation is used, the animation clip (glTF or FBX) used, and + * how animations are blended together with procedural data (such as look at vectors, hand sensors etc.). + * overrideRoleAnimation() is used to change the animation clip (glTF or FBX) associated with a specified + * animation role. To end the role animation and restore the default, use {@link MyAvatar.restoreRoleAnimation}.

+ *

Note: Hand roles only affect the hand. Other "main" roles, like "idleStand", "idleTalk", and "takeoffStand", are full + * body.

*

Note: When using pre-built animation data, it's critical that the joint orientation of the source animation and target * rig are equivalent, since the animation data applies absolute values onto the joints. If the orientations are different, * the avatar will move in unpredictable ways. For more information about avatar joint orientation standards, see * Avatar Standards. * @function MyAvatar.overrideRoleAnimation * @param {string} role - The animation role to override - * @param {string} url - The URL to the animation file. Animation files need to be in FBX format, but only need to contain - * the avatar skeleton and animation data. + * @param {string} url - The URL to the animation file. Animation files need to be in glTF or FBX format, but only need to + * contain the avatar skeleton and animation data. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs + * respectively). + *

Warning: glTF animations currently do not always animate correctly.

* @param {number} fps - The frames per second (FPS) rate for the animation playback. 30 FPS is normal speed. * @param {boolean} loop - true if the animation should loop, false if it shouldn't. * @param {number} firstFrame - The frame the animation should start at. @@ -739,9 +746,9 @@ public: *

Each avatar has an avatar-animation.json file that defines a set of animation roles. Animation roles map to easily * understandable actions that the avatar can perform, such as "idleStand", "idleTalk", or * "walkFwd". To get the full list of roles, use {@link MyAvatar.getAnimationRoles}. For each role, - * the avatar-animation.json defines when the animation is used, the animation clip (FBX) used, and how animations are - * blended together with procedural data (such as look-at vectors, hand sensors etc.). You can change the animation clip - * (FBX) associated with a specified animation role using {@link MyAvatar.overrideRoleAnimation}. + * the avatar-animation.json defines when the animation is used, the animation clip (glTF or FBX) used, and how animations + * are blended together with procedural data (such as look-at vectors, hand sensors etc.). You can change the animation + * clip (glTF or FBX) associated with a specified animation role using {@link MyAvatar.overrideRoleAnimation}. * restoreRoleAnimation() is used to restore a specified animation role's default animation clip. If you have * not specified an override animation for the specified role, this function has no effect. * @function MyAvatar.restoreRoleAnimation @@ -2042,17 +2049,19 @@ public slots: void setEnableDebugDrawDefaultPose(bool isEnabled); /**jsdoc - * Displays animation debug graphics. By default it shows the animation poses used for rendering. - * However, the property MyAvatar.setDebugDrawAnimPoseName can be used to draw a specific animation node. + * Displays animation debug graphics. By default, the animation poses used for rendering are displayed. However, + * {@link MyAvatar.setDebugDrawAnimPoseName} can be used to set a specific animation node to display. * @function MyAvatar.setEnableDebugDrawAnimPose * @param {boolean} enabled - true to show the debug graphics, false to hide. */ void setEnableDebugDrawAnimPose(bool isEnabled); /**jsdoc - * If set it determines which animation debug graphics to draw, when MyAvatar.setEnableDebugDrawAnimPose is set to true. + * Sets the animation node to display when animation debug graphics are enabled with + * {@link MyAvatar.setEnableDebugDrawAnimPose}. * @function MyAvatar.setDebugDrawAnimPoseName - * @param {boolean} enabled - true to show the debug graphics, false to hide. + * @param {string} poseName - The name of the animation node to display debug graphics for. Use "" to reset to + * default. */ void setDebugDrawAnimPoseName(QString poseName); diff --git a/interface/src/scripting/Audio.h b/interface/src/scripting/Audio.h index 5baeee4176..d3bc6b9449 100644 --- a/interface/src/scripting/Audio.h +++ b/interface/src/scripting/Audio.h @@ -66,15 +66,19 @@ class Audio : public AudioScriptingInterface, protected ReadWriteLockable { * @property {boolean} pushToTalkHMD - true if HMD push-to-talk is enabled, otherwise false. * @property {boolean} pushingToTalk - true if the user is currently pushing-to-talk, otherwise * false. - * @property {number} avatarGain - The gain (relative volume) that avatars' voices are played at. This gain is used at the server. - * @property {number} localInjectorGain - The gain (relative volume) that local injectors (local environment sounds) are played at. - * @property {number} serverInjectorGain - The gain (relative volume) that server injectors (server environment sounds) are played at. This gain is used at the server. - * @property {number} systemInjectorGain - The gain (relative volume) that system sounds are played at. - * @property {number} pushingToTalkOutputGainDesktop - The gain (relative volume) that all sounds are played at when the user is holding - * the push-to-talk key in Desktop mode. - * @property {boolean} acousticEchoCancellation - true if audio-echo-cancellation is enabled, otherwise - * false. When enabled, sound from the audio output will be suppressed when it echos back to the - * input audio signal. + + * @property {number} avatarGain - The gain (relative volume in dB) that avatars' voices are played at. This gain is used + * at the server. + * @property {number} localInjectorGain - The gain (relative volume in dB) that local injectors (local environment sounds) + * are played at. + * @property {number} serverInjectorGain - The gain (relative volume in dB) that server injectors (server environment + * sounds) are played at. This gain is used at the server. + * @property {number} systemInjectorGain - The gain (relative volume in dB) that system sounds are played at. + * @property {number} pushingToTalkOutputGainDesktop - The gain (relative volume in dB) that all sounds are played at when + * the user is holding the push-to-talk key in desktop mode. + * @property {boolean} acousticEchoCancellation - true if acoustic echo cancellation is enabled, otherwise + * false. When enabled, sound from the audio output is suppressed when it echos back to the input audio + * signal. * * @comment The following properties are from AudioScriptingInterface.h. * @property {boolean} isStereoInput - true if the input audio is being used in stereo, otherwise @@ -301,18 +305,18 @@ public: Q_INVOKABLE bool getRecording(); /**jsdoc - * Sets the output volume gain that will be used when the user is holding the Push to Talk key. + * Sets the output volume gain that will be used when the user is holding the push-to-talk key. * Should be negative. * @function Audio.setPushingToTalkOutputGainDesktop - * @param {number} gain - The output volume gain (dB) while using PTT. + * @param {number} gain - The output volume gain (dB) while using push-to-talk. */ Q_INVOKABLE void setPushingToTalkOutputGainDesktop(float gain); /**jsdoc - * Gets the output volume gain that is used when the user is holding the Push to Talk key. + * Gets the output volume gain that is used when the user is holding the push-to-talk key. * Should be negative. * @function Audio.getPushingToTalkOutputGainDesktop - * @returns {number} gain - The output volume gain (dB) while using PTT. + * @returns {number} gain - The output volume gain (dB) while using push-to-talk. */ Q_INVOKABLE float getPushingToTalkOutputGainDesktop(); @@ -457,7 +461,7 @@ signals: /**jsdoc * Triggered when the avatar gain changes. * @function Audio.avatarGainChanged - * @param {number} gain - The new avatar gain value. + * @param {number} gain - The new avatar gain value (dB). * @returns {Signal} */ void avatarGainChanged(float gain); @@ -465,7 +469,7 @@ signals: /**jsdoc * Triggered when the local injector gain changes. * @function Audio.localInjectorGainChanged - * @param {number} gain - The new local injector gain value. + * @param {number} gain - The new local injector gain value (dB). * @returns {Signal} */ void localInjectorGainChanged(float gain); @@ -473,7 +477,7 @@ signals: /**jsdoc * Triggered when the server injector gain changes. * @function Audio.serverInjectorGainChanged - * @param {number} gain - The new server injector gain value. + * @param {number} gain - The new server injector gain value (dB). * @returns {Signal} */ void serverInjectorGainChanged(float gain); @@ -481,7 +485,7 @@ signals: /**jsdoc * Triggered when the system injector gain changes. * @function Audio.systemInjectorGainChanged - * @param {number} gain - The new system injector gain value. + * @param {number} gain - The new system injector gain value (dB). * @returns {Signal} */ void systemInjectorGainChanged(float gain); @@ -489,7 +493,7 @@ signals: /**jsdoc * Triggered when the push to talk gain changes. * @function Audio.pushingToTalkOutputGainDesktopChanged - * @param {number} gain - The new output gain value. + * @param {number} gain - The new output gain value (dB). * @returns {Signal} */ void pushingToTalkOutputGainDesktopChanged(float gain); diff --git a/interface/src/scripting/PlatformInfoScriptingInterface.h b/interface/src/scripting/PlatformInfoScriptingInterface.h index f59d476f0c..25cdc99577 100644 --- a/interface/src/scripting/PlatformInfoScriptingInterface.h +++ b/interface/src/scripting/PlatformInfoScriptingInterface.h @@ -15,7 +15,7 @@ class QScriptValue; /**jsdoc - * The PlatformInfo API provides information about the computer and controllers being used. + * The PlatformInfo API provides information about the hardware platform being used. * * @namespace PlatformInfo * @@ -31,6 +31,21 @@ public: PlatformInfoScriptingInterface(); virtual ~PlatformInfoScriptingInterface(); + /**jsdoc + *

The platform tier of a computer is an indication of its rendering capability.

+ * + * + * + * + * + * + * + * + * + * + *
ValueNameDescription
0UNKNOWNUnknown rendering capability.
1LOWLow-end PC, capable of rendering low-quality graphics.
2MIDBusiness-class PC, capable of rendering medium-quality graphics.
3HIGHHigh-end PC, capable of rendering high-quality graphics.
+ * @typedef {number} PlatformInfo.PlatformTier + */ // Platform tier enum type enum PlatformTier { UNKNOWN = platform::Profiler::Tier::UNKNOWN, @@ -50,23 +65,18 @@ public slots: /**jsdoc * Gets the operating system type. * @function PlatformInfo.getOperatingSystemType - * @returns {string} "WINDOWS", "MACOS", or "UNKNOWN". + * @returns {string} The operating system type: "WINDOWS", "MACOS", or "UNKNOWN". * @deprecated This function is deprecated and will be removed. - * use getComputer()["OS"] instead + * Use JSON.parse({@link PlatformInfo.getComputer|PlatformInfo.getComputer()}).OS instead. */ QString getOperatingSystemType(); /**jsdoc - * Gets information on the CPU. + * Gets information on the CPU model. * @function PlatformInfo.getCPUBrand * @returns {string} Information on the CPU. - * @example Report the CPU being used. - * print("CPU: " + PlatformInfo.getCPUBrand()); - * // Example: Intel(R) Core(TM) i7-7820HK CPU @ 2.90GHz * @deprecated This function is deprecated and will be removed. - * use getNumCPUs() to know the number of CPUs in the hardware, at least one is expected - * use getCPU(0)["vendor"] to get the brand of the vendor - * use getCPU(0)["model"] to get the model name of the cpu + * Use JSON.parse({@link PlatformInfo.getCPU|PlatformInfo.getCPU(0)}).model instead. */ QString getCPUBrand(); @@ -75,27 +85,27 @@ public slots: * @function PlatformInfo.getNumLogicalCores * @returns {number} The number of logical CPU cores. * @deprecated This function is deprecated and will be removed. - * use getCPU(0)["numCores"] instead + * Use JSON.parse({@link PlatformInfo.getCPU|PlatformInfo.getCPU(0)}).numCores instead. */ unsigned int getNumLogicalCores(); /**jsdoc - * Returns the total system memory in megabytes. + * Gets the total amount of usable physical memory, in MB. * @function PlatformInfo.getTotalSystemMemoryMB * @returns {number} The total system memory in megabytes. * @deprecated This function is deprecated and will be removed. - * use getMemory()["memTotal"] instead + * Use JSON.parse({@link PlatformInfo.getMemory|PlatformInfo.getMemory()}).memTotal instead. */ int getTotalSystemMemoryMB(); /**jsdoc - * Gets the graphics card type. + * Gets the model of the graphics card currently being used. * @function PlatformInfo.getGraphicsCardType - * @returns {string} The graphics card type. + * @returns {string} The model of the graphics card currently being used. * @deprecated This function is deprecated and will be removed. - * use getNumGPUs() to know the number of GPUs in the hardware, at least one is expected - * use getGPU(getMasterGPU())["vendor"] to get the brand of the vendor - * use getGPU(getMasterGPU())["model"] to get the model name of the gpu + * Use JSON.parse({@link PlatformInfo.getGPU|PlatformInfo.getGPU(} + * {@link PlatformInfo.getMasterGPU|PlatformInfo.getMasterGPU() )}).model + * instead. */ QString getGraphicsCardType(); @@ -117,139 +127,150 @@ public slots: * Checks whether HTML on 3D surfaces (e.g., Web entities) is supported. * @function PlatformInfo.has3DHTML * @returns {boolean} true if the current display supports HTML on 3D surfaces, false if it - * doesn't. + * doesn't. */ bool has3DHTML(); /**jsdoc * Checks whether Interface is running on a stand-alone HMD device (CPU incorporated into the HMD display). * @function PlatformInfo.isStandalone - * @returns {boolean} true if Interface is running on a stand-alone device, false if it isn't. + * @returns {boolean} true if Interface is running on a stand-alone HMD device, false if it isn't. */ bool isStandalone(); /**jsdoc - * Get the number of CPUs. - * @function PlatformInfo.getNumCPUs - * @returns {number} The number of CPUs detected on the hardware platform. - */ + * Gets the number of CPUs. + * @function PlatformInfo.getNumCPUs + * @returns {number} The number of CPUs. + */ int getNumCPUs(); /**jsdoc - * Get the index of the master CPU. - * @function PlatformInfo.getMasterCPU - * @returns {number} The index of the master CPU detected on the hardware platform. - */ + * Gets the index number of the master CPU. + * @function PlatformInfo.getMasterCPU + * @returns {number} The index of the master CPU. + */ int getMasterCPU(); /**jsdoc - * Get the description of the CPU at the index parameter - * expected fields are: - * - cpuVendor... - * @param index The index of the CPU of the platform - * @function PlatformInfo.getCPU - * @returns {string} The CPU description json field - */ + * Gets the platform description of a CPU. + * @function PlatformInfo.getCPU + * @param {number} index - The index number of the CPU. + * @returns {string} The CPU's {@link PlatformInfo.CPUDescription|CPUDescription} information as a JSON string. + * @example Report details of the computer's CPUs. + * var numCPUs = PlatformInfo.getNumCPUs(); + * print("Number of CPUs: " + numCPUs); + * for (var i = 0; i < numCPUs; i++) { + * var cpuDescription = PlatformInfo.getCPU(i); + * print("CPU " + i + ": " + cpuDescription); + * } + */ QString getCPU(int index); /**jsdoc - * Get the number of GPUs. + * Gets the number of GPUs. * @function PlatformInfo.getNumGPUs - * @returns {number} The number of GPUs detected on the hardware platform. + * @returns {number} The number of GPUs. */ int getNumGPUs(); /**jsdoc - * Get the index of the master GPU. - * @function PlatformInfo.getMasterGPU - * @returns {number} The index of the master GPU detected on the hardware platform. - */ + * Gets the index number of the master GPU. + * @function PlatformInfo.getMasterGPU + * @returns {number} The index of the master GPU. + */ int getMasterGPU(); /**jsdoc - * Get the description of the GPU at the index parameter - * expected fields are: - * - vendor, model... - * @param index The index of the GPU of the platform + * Gets the platform description of a GPU. + * @param {number} index - The index number of the GPU. * @function PlatformInfo.getGPU - * @returns {string} The GPU description json field + * @returns {string} The GPU's {@link PlatformInfo.GPUDescription|GPUDescription} information as a JSON string. + * @example Report details of the computer's GPUs. + * var numGPUs = PlatformInfo.getNumGPUs(); + * print("Number of GPUs: " + numGPUs); + * for (var i = 0; i < numGPUs; i++) { + * var gpuDescription = PlatformInfo.getGPU(i); + * print("GPU " + i + ": " + gpuDescription); + * } */ QString getGPU(int index); /**jsdoc - * Get the number of Displays. - * @function PlatformInfo.getNumDisplays - * @returns {number} The number of Displays detected on the hardware platform. - */ + * Gets the number of displays. + * @function PlatformInfo.getNumDisplays + * @returns {number} The number of displays. + */ int getNumDisplays(); /**jsdoc - * Get the index of the master Display. - * @function PlatformInfo.getMasterDisplay - * @returns {number} The index of the master Display detected on the hardware platform. - */ + * Gets the index number of the master display. + * @function PlatformInfo.getMasterDisplay + * @returns {number} The index of the master display. + */ int getMasterDisplay(); /**jsdoc - * Get the description of the Display at the index parameter - * expected fields are: - * - DisplayVendor... - * @param index The index of the Display of the platform - * @function PlatformInfo.getDisplay - * @returns {string} The Display description json field - */ + * Gets the platform description of a display. + * @param {number} index - The index number of the display. + * @function PlatformInfo.getDisplay + * @returns {string} The display's {@link PlatformInfo.DisplayDescription|DisplayDescription} information as a JSON string. + * @example Report details of the systems's displays. + * var numDisplays = PlatformInfo.getNumDisplays(); + * print("Number of displays: " + numDisplays); + * for (var i = 0; i < numDisplays; i++) { + * var displayDescription = PlatformInfo.getDisplay(i); + * print("Display " + i + ": " + displayDescription); + * } + */ QString getDisplay(int index); /**jsdoc - * Get the description of the Memory - * expected fields are: - * - MemoryVendor... - * @function PlatformInfo.getMemory - * @returns {string} The Memory description json field - */ + * Gets the platform description of computer memory. + * @function PlatformInfo.getMemory + * @returns {string} The computer's {@link PlatformInfo.MemoryDescription|MemoryDescription} information as a JSON string. + * @example Report details of the computer's memory. + * print("Memory: " + PlatformInfo.getMemory()); + */ QString getMemory(); /**jsdoc - * Get the description of the Computer - * expected fields are: - * - ComputerVendor... - * @function PlatformInfo.getComputer - * @returns {string} The Computer description json field - */ + * Gets the platform description of the computer. + * @function PlatformInfo.getComputer + * @returns {string} The {@link PlatformInfo.ComputerDescription|ComputerDescription} information as a JSON string. + */ QString getComputer(); /**jsdoc - * Get the complete description of the Platform as an aggregated Json - * The expected object description is: - * { "computer": {...}, "memory": {...}, "cpus": [{...}, ...], "gpus": [{...}, ...], "displays": [{...}, ...] } - * @function PlatformInfo.getPlatform - * @returns {string} The Platform description json field - */ + * Gets the complete description of the computer as a whole. + * @function PlatformInfo.getPlatform + * @returns {string} The {@link PlatformInfo.PlatformDescription|PlatformDescription} information as a JSON string. + */ QString getPlatform(); /**jsdoc - * Get the Platform TIer profiled on startup of the Computer - * Platform Tier is an integer/enum value: - * UNKNOWN = 0, LOW = 1, MID = 2, HIGH = 3 - * @function PlatformInfo.getTierProfiled - * @returns {number} The Platform Tier profiled on startup. - */ + * Gets the platform tier of the computer, profiled at Interface start-up. + * @function PlatformInfo.getTierProfiled + * @returns {PlatformInfo.PlatformTier} The platform tier of the computer. + * @example Report the platform tier of the computer. + * var platformTier = PlatformInfo.getTierProfiled(); + * var platformTierName = PlatformInfo.getPlatformTierNames()[platformTier]; + * print("Platform tier: " + platformTier + ", " + platformTierName); + */ PlatformTier getTierProfiled(); /**jsdoc - * Get the Platform Tier possible Names as an array of strings - * Platform Tier names are: - * [ "UNKNOWN", "LOW", "MID", "HIGH" ] - * @function PlatformInfo.getPlatformTierNames - * @returns {string} The array of names matching the number returned from PlatformInfo.getTierProfiled - */ + * Gets the names of the possible platform tiers, per {@link PlatformInfo.PlatformTier}. + * @function PlatformInfo.getPlatformTierNames + * @returns {string[]} The names of the possible platform tiers. + */ QStringList getPlatformTierNames(); /**jsdoc - * Gets whether the current hardware can render using the Deferred method. - * @function PlatformInfo.isRenderMethodDeferredCapable - * @returns {bool} true if the current hardware can render using the Deferred method; false otherwise. - */ + * Gets whether the current hardware can use deferred rendering. + * @function PlatformInfo.isRenderMethodDeferredCapable + * @returns {boolean} true if the current hardware can use deferred rendering, false if it can't. + */ bool isRenderMethodDeferredCapable(); }; diff --git a/interface/src/scripting/RenderScriptingInterface.h b/interface/src/scripting/RenderScriptingInterface.h index 9b96448c9d..1c2443144a 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 - 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: diff --git a/interface/src/ui/overlays/Overlays.cpp b/interface/src/ui/overlays/Overlays.cpp index be371c900b..100711d69b 100644 --- a/interface/src/ui/overlays/Overlays.cpp +++ b/interface/src/ui/overlays/Overlays.cpp @@ -1740,7 +1740,9 @@ QVector Overlays::findOverlays(const glm::vec3& center, float radius) { * parented to if parentID is set. Use 65535 or -1 to parent to the parent's position and orientation rather * than a joint. * - * @property {string} url - The URL of the FBX or OBJ model used for the overlay. + * @property {string} url - The URL of the glTF, FBX, or OBJ model used for the overlay. glTF models may be in JSON or binary + * format (".gltf" or ".glb" URLs respectively). Baked models' URLs have ".baked" before the file type. Model files may + * also be compressed in GZ format, in which case the URL ends in ".gz". * @property {number} loadPriority=0.0 - The priority for loading and displaying the overlay. Overlays with higher values load * first. Currently not used. * @property {Object.|string} textures - Texture name, URL pairs used when rendering the model in place of the diff --git a/libraries/avatars/src/AvatarData.cpp b/libraries/avatars/src/AvatarData.cpp index 22b070464d..7d5f38db40 100755 --- a/libraries/avatars/src/AvatarData.cpp +++ b/libraries/avatars/src/AvatarData.cpp @@ -2860,7 +2860,8 @@ glm::vec3 AvatarData::getAbsoluteJointTranslationInObjectFrame(int index) const /**jsdoc * Information on an attachment worn by the avatar. * @typedef {object} AttachmentData - * @property {string} modelUrl - The URL of the model file. Models can be FBX or OBJ format. + * @property {string} modelUrl - The URL of the glTF, FBX, or OBJ model file. glTF models may be in JSON or binary format + * (".gltf" or ".glb" URLs respectively). * @property {string} jointName - The name of the joint that the attachment is parented to. * @property {Vec3} translation - The offset from the joint that the attachment is positioned at. * @property {Vec3} rotation - The rotation applied to the model relative to the joint orientation. diff --git a/libraries/avatars/src/AvatarData.h b/libraries/avatars/src/AvatarData.h index 3c8e2d6fcc..20c5b1900d 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:

* * * @@ -1268,12 +1267,11 @@ public: /**jsdoc * Attaches a model to your avatar. For example, you can give your avatar a hat to wear, a guitar to hold, or a surfboard to * stand on. - *

Note: Attached models are models only; they are not entities and can not be manipulated using the {@link Entities} API. - * Nor can you use this function to attach an entity (such as a sphere or a box) to your avatar.

* @function Avatar.attach - * @param {string} modelURL - The URL of the model to attach. Models can be .FBX or .OBJ format. - * @param {string} [jointName=""] - The name of the avatar joint (see {@link MyAvatar.getJointNames} or {@link Avatar.getJointNames}) to attach the model - * to. + * @param {string} modelURL - The URL of the glTF, FBX, or OBJ model to attach. glTF models may be in JSON or binary format + * (".gltf" or ".glb" URLs respectively). + * @param {string} [jointName=""] - The name of the avatar joint (see {@link MyAvatar.getJointNames} or + * {@link Avatar.getJointNames}) to attach the model to. * @param {Vec3} [translation=Vec3.ZERO] - The offset to apply to the model relative to the joint position. * @param {Quat} [rotation=Quat.IDENTITY] - The rotation to apply to the model relative to the joint orientation. * @param {number} [scale=1.0] - The scale to apply to the model. diff --git a/libraries/entities/src/AnimationPropertyGroup.cpp b/libraries/entities/src/AnimationPropertyGroup.cpp index 7f9225bd6c..38230b4f50 100644 --- a/libraries/entities/src/AnimationPropertyGroup.cpp +++ b/libraries/entities/src/AnimationPropertyGroup.cpp @@ -50,8 +50,10 @@ bool operator!=(const AnimationPropertyGroup& a, const AnimationPropertyGroup& b /**jsdoc * An animation is configured by the following properties: * @typedef {object} Entities.AnimationProperties - * @property {string} url="" - The URL of the FBX file that has the animation. - * @property {boolean} allowTranslation=true - true to enable translations contained in the animation to be + * @property {string} url="" - The URL of the glTF or FBX file that has the animation. glTF files may be in JSON or binary + * format (".gltf" or ".glb" URLs respectively). + *

Warning: glTF animations currently do not always animate correctly.

+ * @property {boolean} allowTranslation=true - true to enable translations contained in the animation to be * played, false to disable translations. * @property {number} fps=30 - The speed in frames/s that the animation is played at. * @property {number} firstFrame=0 - The first frame to play in the animation. diff --git a/libraries/entities/src/EntityItemProperties.cpp b/libraries/entities/src/EntityItemProperties.cpp index 42ce276aca..c16839dc1a 100644 --- a/libraries/entities/src/EntityItemProperties.cpp +++ b/libraries/entities/src/EntityItemProperties.cpp @@ -980,8 +980,8 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { * value is specified then the model is automatically sized to its * {@link Entities.EntityProperties|naturalDimensions}. * @property {string} modelURL="" - The URL of the glTF, FBX, or OBJ model. glTF models may be in JSON or binary format - * (".gltf" or ".glb" URLs respectively). Baked FBX models' URLs end in ".baked.fbx". Model files may also be compressed in GZ - * format, in which case the URL ends in ".gz". + * (".gltf" or ".glb" URLs respectively). Baked models' URLs have ".baked" before the file type. Model files may also be + * compressed in GZ format, in which case the URL ends in ".gz". * @property {Vec3} modelScale - The scale factor applied to the model's dimensions. *

Deprecated: This property is deprecated and will be removed.

* @property {string} textures="" - A JSON string of texture name, URL pairs used when rendering the model in place of the @@ -1307,11 +1307,11 @@ EntityPropertyFlags EntityItemProperties::getChangedProperties() const { * @property {number} rightMargin=0.0 - The right margin, in meters. * @property {number} topMargin=0.0 - The top margin, in meters. * @property {number} bottomMargin=0.0 - The bottom margin, in meters. - * @property {boolean} unlit=false - true if the entity should be unaffected by lighting. Otherwise, the text - * is lit by the keylight and local lights. - * @property {string} font="" - The text is rendered with this font. Can be one of the following: CourierInconsolata, Roboto, Timeless, or a path to a .sdff file. - * @property {TextEffect} textEffect="none" - The effect that is applied to the text. + * @property {boolean} unlit=false - true if the entity is unaffected by lighting, false if it is lit + * by the key light and local lights. + * @property {string} font="" - The font to render the text with. It can be one of the following: "Courier""Inconsolata", "Roboto", "Timeless", or a path to a .sdff file. + * @property {Entities.TextEffect} textEffect="none" - The effect that is applied to the text. * @property {Color} textEffectColor=255,255,255 - The color of the effect. * @property {number} textEffectThickness=0.2 - The magnitude of the text effect, range 0.0 – 0.5. * @property {BillboardMode} billboardMode="none" - Whether the entity is billboarded to face the camera. diff --git a/libraries/entities/src/EntityTypes.h b/libraries/entities/src/EntityTypes.h index 8fdc752cac..4106eb8054 100644 --- a/libraries/entities/src/EntityTypes.h +++ b/libraries/entities/src/EntityTypes.h @@ -59,7 +59,7 @@ public: * "Sphere". If an entity of type Box or Shape has its shape set * to "Sphere" then its type will be reported as "Sphere". * - * + * * * * diff --git a/libraries/entities/src/KeyLightPropertyGroup.h b/libraries/entities/src/KeyLightPropertyGroup.h index facbf88f3c..6441c30d50 100644 --- a/libraries/entities/src/KeyLightPropertyGroup.h +++ b/libraries/entities/src/KeyLightPropertyGroup.h @@ -37,10 +37,10 @@ class ReadBitstreamToTreeParams; * are cast by avatars, plus {@link Entities.EntityProperties-Model|Model} and * {@link Entities.EntityProperties-Shape|Shape} entities that have their * {@link Entities.EntityProperties|canCastShadow} property set to true. - * @property {number} shadowBias=0.5 - The bias of the shadows cast by the light. Use this to fine-tune your shadows to your scene - * to prevent shadow acne and peter panning. In the range 0.0 – 1.0. - * @property {number} shadowMaxDistance=40.0 - The max distance from your view at which shadows will be computed. Higher values will - * cover more of your scene, but with less precision. In the range 1.0 – 250.0. + * @property {number} shadowBias=0.5 - The bias of the shadows cast by the light, range 0.0 – + * 1.0. This fine-tunes shadows cast by the light, to prevent shadow acne and peter panning. + * @property {number} shadowMaxDistance=40.0 - The maximum distance from the camera position at which shadows will be computed, + * range 1.0 – 250.0. Higher values cover more of the scene but with less precision. */ class KeyLightPropertyGroup : public PropertyGroup { public: diff --git a/libraries/material-networking/src/material-networking/MaterialCache.cpp b/libraries/material-networking/src/material-networking/MaterialCache.cpp index fd218fe074..087e1ca049 100644 --- a/libraries/material-networking/src/material-networking/MaterialCache.cpp +++ b/libraries/material-networking/src/material-networking/MaterialCache.cpp @@ -120,7 +120,8 @@ NetworkMaterialResource::ParsedMaterials NetworkMaterialResource::parseJSONMater * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. * @property {number|string} opacity=1.0 - The opacity, range 0.0 – 1.0. * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. - * @property {boolean|string} unlit=false - true if the material is not lit, false if it is. + * @property {boolean|string} unlit=false - true if the material is unaffected by lighting, false if + * it is lit by the key light and local lights. * Set to "fallthrough" to fall through to the material below. "hifi_pbr" model only. * @property {ColorFloat|RGBS|string} albedo - The albedo color. A {@link ColorFloat} value is treated as sRGB and must have * component values in the range 0.0 – 1.0. A {@link RGBS} value can be either RGB or sRGB. diff --git a/libraries/platform/src/platform/backend/Platform.cpp b/libraries/platform/src/platform/backend/Platform.cpp index c3abcce5f1..8b52b9cc29 100644 --- a/libraries/platform/src/platform/backend/Platform.cpp +++ b/libraries/platform/src/platform/backend/Platform.cpp @@ -10,19 +10,52 @@ #include "../Platform.h" #include "../PlatformKeys.h" +/**jsdoc + * Information on the computer platform as a whole. + * @typedef {object} PlatformInfo.PlatformDescription + * @property {PlatformInfo.ComputerDescription} computer - Information on the computer. + * @property {PlatformInfo.CPUDescription[]} cpus - Information on the computer's CPUs. + * @property {PlatformInfo.DisplayDescription[]} displays - Information on the computer's displays. + * @property {PlatformInfo.GPUDescription[]} gpus - Information on the computer's GPUs. + * @property {PlatformInfo.GraphicsAPIDescription[]} graphicsAPIs - Information on the computer's graphics APIs. + * @property {PlatformInfo.MemoryDescription} memory - Information on the computer's memory. + * @property {PlatformInfo.NICDescription} nics - Information on the computer's network cards. + */ namespace platform { namespace keys { const char* UNKNOWN = "UNKNOWN"; + /**jsdoc + * Information on a CPU. + * @typedef {object} PlatformInfo.CPUDescription + * @property {string} vendor - The CPU vendor (e.g., "Intel" or "AMD"). + * @property {string} model - The CPU model. + * @property {number} numCores - The number of logical cores. + * @property {boolean} isMaster - true if the CPU is the "master" or primary CPU, false or + * undefined if it isn't. + */ namespace cpu { const char* vendor = "vendor"; const char* vendor_Intel = "Intel"; const char* vendor_AMD = "AMD"; const char* model = "model"; - const char* clockSpeed = "clockSpeed"; + const char* clockSpeed = "clockSpeed"; // FIXME: Not used. const char* numCores = "numCores"; const char* isMaster = "isMaster"; } + + /**jsdoc + * Information on a GPU. + * @typedef {object} PlatformInfo.GPUDescription + * @property {string} vendor - The GPU vendor (e.g., "NVIDIA", "AMD", or "Intel"). + * @property {string} model - The GPU model. + * @property {string} driver - The GPU driver version. + * @property {number} videoMemory - The size of the GPU's video memory, in MB. + * @property {number[]} displays - The index numbers of the displays currently being driven by the GPU. An empty array if + * the GPU is currently not driving any displays. + * @property {boolean} isMaster - true if the GPU is the "master" or primary GPU, false or + * undefined if it isn't. + */ namespace gpu { const char* vendor = "vendor"; const char* vendor_NVIDIA = "NVIDIA"; @@ -35,6 +68,45 @@ namespace platform { namespace keys { const char* displays = "displays"; const char* isMaster = "isMaster"; } + + /**jsdoc + * Information on a graphics API. + * @typedef {object} PlatformInfo.GraphicsAPIDescription + * @property {string} name - The name of the graphics API. + * @property {string} version - The version of the graphics API. + * + * @property {string} [renderer] - If an OpenGL API, then the graphics card that performs the rendering. + * @property {string} [vendor] - If an OpenGL API, then the OpenGL vendor. + * @property {string} [shadingLanguageVersion] - If an OpenGL API, then the shading language version. + * @property {string[]} [extensions] - If an OpenGL API, then the list of OpenGL extensions supported. + * + * @property {PlatformInfo.VulkanAPIDescription[]} [devices] - If a Vulkan API, then the devices provided in the API. + */ + /**jsdoc + * Information on a Vulkan graphics API. + * @typedef {object} PlatformInfo.VulkanAPIDescription + * @property {string} + * @property {string} driverVersion - The driver version. + * @property {string} apiVersion - The API version. + * @property {string} deviceType - The device type. + * @property {string} vendor - The device vendor. + * @property {string} name - The device name. + * @property {string[]} extensions - The list of Vulkan extensions supported. + * @property {PlatformInfo.VulkanQueueDescription[]} queues - The Vulkan queues available. + * @property {PlatformInfo.VulkanHeapDescription[]} heaps - The Vulkan heaps available. + */ + /**jsdoc + * Information on a Vulkan queue. + * @typedef {object} PlatformInfo.VulkanQueueDescription + * @property {string} flags - The Vulkan queue flags. + * @property {number} count - The queue count. + */ + /**jsdoc + * Information on a Vulkan heap. + * @typedef {object} PlatformInfo.VulkanHeapDescription + * @property {string} flags - The Vulkan heap flags. + * @property {number} size - The heap size. + */ namespace graphicsAPI { const char* name = "name"; const char* version = "version"; @@ -74,10 +146,38 @@ namespace platform { namespace keys { } } } + + /**jsdoc + * Information on a network card. + * @typedef {object} PlatformInfo.NICDescription + * @property {string} name - The name of the network card. + * @property {string} mac - The MAC address of the network card. + */ namespace nic { const char* mac = "mac"; const char* name = "name"; } + + /**jsdoc + * Information on a display. + * @typedef {object} PlatformInfo.DisplayDescription + * @property {string} description - The display's description. + * @property {string} deviceName - The display's device name. + * @property {number} boundsLeft - The pixel coordinate of the left edge of the display (e.g., 0). + * @property {number} boundsRight - The pixel coordinate of the right edge of the display (e.g., 1920). + * @property {number} boundsTop - The pixel coordinate of the top edge of the display (e.g., 0). + * @property {number} boundsBottom - The pixel coordinate of the bottom edge of the display (e.g., 1080). + * @property {number} gpu - The index number of the GPU that's driving the display. + * @property {number} ppi - The physical dots per inch of the display. + * @property {number} ppiDesktop - The logical dots per inch of the desktop as used by the operating system. + * @property {number} physicalWidth - The physical width of the display, in inches. + * @property {number} physicalHeight - The physical height of the display, in inches. + * @property {number} modeRefreshrate - The refresh rate of the current display mode, in Hz. + * @property {number} modeWidth - The width of the current display mode, in pixels. + * @property {number} modeHeight - The height of the current display mode, in pixels. + * @property {boolean} isMaster - true if the GPU is the "master" or primary display, false or + * undefined if it isn't. + */ namespace display { const char* description = "description"; const char* name = "deviceName"; @@ -95,9 +195,40 @@ namespace platform { namespace keys { const char* modeHeight = "modeHeight"; const char* isMaster = "isMaster"; } + + /**jsdoc + * Information on the computer's memory. + * @typedef {object} PlatformInfo.MemoryDescription + * @property {number} memTotal - The total amount of usable physical memory, in MB. + */ namespace memory { const char* memTotal = "memTotal"; } + + /**jsdoc + * Information on the computer. + * @typedef {object} PlatformInfo.ComputerDescription + * @property {PlatformInfo.ComputerOS} OS - The operating system. + * @property {string} OSversion - The operating system version. + * @property {string} vendor - The computer vendor. + * @property {string} model - The computer model. + * @property {PlatformInfo.PlatformTier} profileTier - The platform tier of the computer, profiled at Interface start-up. + */ + /**jsdoc + *

The computer operating system.

+ *
ValueDescription{@link Entities.EntityProperties-Sphere|EntityProperties-Sphere}
"Model"A mesh model from a glTf, FBX, or OBJ file.
"Model"A mesh model from a glTF, FBX, or OBJ file.{@link Entities.EntityProperties-Model|EntityProperties-Model}
"Text"A pane of text oriented in space.{@link Entities.EntityProperties-Text|EntityProperties-Text}
+ * + * + * + * + * + * + * + * + * + *
ValueDescription
"WINDOWS"Windows.
"MACOS"Mac OS.
"LINUX"Linux.
"ANDROID"Android.
+ * @typedef {string} PlatformInfo.ComputerOS + */ namespace computer { const char* OS = "OS"; const char* OS_WINDOWS = "WINDOWS"; diff --git a/libraries/shared/src/DebugDraw.h b/libraries/shared/src/DebugDraw.h index 785e549c03..9e3140ca9b 100644 --- a/libraries/shared/src/DebugDraw.h +++ b/libraries/shared/src/DebugDraw.h @@ -22,8 +22,9 @@ #include /**jsdoc - * Helper functions to render ephemeral debug markers and lines. - * DebugDraw markers and lines are only visible locally, they are not visible by other users. + * The DebugDraw API renders debug markers and lines. These markers are only visible locally; they are not visible + * to other users. + * * @namespace DebugDraw * * @hifi-interface @@ -41,57 +42,107 @@ public: ~DebugDraw(); /**jsdoc - * Draws a line in world space, but it will only be visible for a single frame. + * Draws a line in world space, visible for a single frame. To make the line visually persist, you need to repeatedly draw + * it. * @function DebugDraw.drawRay - * @param {Vec3} start - start position of line in world space. - * @param {Vec3} end - end position of line in world space. - * @param {Vec4} color - color of line, each component should be in the zero to one range. x = red, y = blue, z = green, w = alpha. + * @param {Vec3} start - The start position of the line, in world coordinates. + * @param {Vec3} end - The end position of the line, in world coordinates. + * @param {Vec4} color - The color of the line. Each component should be in the range 0.0 – + * 1.0, with x = red, y = green, z = blue, and w = alpha. + * @example Draw a red ray from your initial avatar position to 10m in front of it. + * var start = MyAvatar.position; + * var end = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -10 })); + * var color = { x: 1.0, y: 0.0, z: 0.0, w: 1.0 }; + * + * Script.update.connect(function () { + * DebugDraw.drawRay(start, end, color); + * }); */ Q_INVOKABLE void drawRay(const glm::vec3& start, const glm::vec3& end, const glm::vec4& color); /**jsdoc - * Draws a line in world space, but it will only be visible for a single frame. - * @function DebugDraw.drawRay - * @param {Vec3} start - start position of line in world space. - * @param {Vec3} end - end position of line in world space. - * @param {Vec4} color - color of line, each component should be in the zero to one range. x = red, y = blue, z = green, w = alpha. - */ + * Draws lines in world space, visible for a single frame. To make the lines visually persist, you need to repeatedly draw + * them. + *

Note: Currently doesn't work. + * @function DebugDraw.drawRays + * @param {Vec3Pair[]} lines - The start and end points of the lines to draw. + * @param {Vec4} color - The color of the lines. Each component should be in the range 0.0 – + * 1.0, with x = red, y = green, z = blue, and w = alpha. + * @param {Vec3} [translation=0,0,0] - A translation applied to each line. + * @param {Quat} [rotation=Quat.IDENTITY] - A rotation applied to each line. + * @example Draw a red "V" in front of your initial avatar position. + * var lines = [ + * [{ x: -1, y: 0.5, z: 0 }, { x: 0, y: 0, z: 0 }], + * [{ x: 0, y: 0, z: 0 }, { x: 1, y: 0.5, z: 0 }] + * ]; + * var color = { x: 1, y: 0, z: 0, w: 1 }; + * var translation = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -5 })); + * var rotation = MyAvatar.orientation; + * + * Script.update.connect(function () { + * DebugDraw.drawRays(lines, color, translation, rotation); + * }); + */ Q_INVOKABLE void drawRays(const std::vector>& lines, const glm::vec4& color, const glm::vec3& translation = glm::vec3(0.0f, 0.0f, 0.0f), const glm::quat& rotation = glm::quat(1.0f, 0.0f, 0.0f, 0.0f)); /**jsdoc - * Adds a debug marker to the world. This marker will be drawn every frame until it is removed with DebugDraw.removeMarker. - * This can be called repeatedly to change the position of the marker. + * Adds or updates a debug marker in world coordinates. This marker is drawn every frame until it is removed using + * {@link DebugDraw.removeMarker|removeMarker}. If a world coordinates debug marker of the specified name + * already exists, its parameters are updated. * @function DebugDraw.addMarker - * @param {string} key - name to uniquely identify this marker, later used for DebugDraw.removeMarker. - * @param {Quat} rotation - start position of line in world space. - * @param {Vec3} position - position of the marker in world space. - * @param {Vec4} color - color of the marker. + * @param {string} key - A name that uniquely identifies the marker. + * @param {Quat} rotation - The orientation of the marker in world coordinates. + * @param {Vec3} position - The position of the market in world coordinates. + * @param {Vec4} color - The color of the marker. + * @example Briefly draw a debug marker in front of your avatar, in world coordinates. + * var MARKER_NAME = "my marker"; + * DebugDraw.addMarker( + * MARKER_NAME, + * Quat.ZERO, + * Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5})), + * { red: 255, green: 0, blue: 0 } + * ); + * Script.setTimeout(function () { + * DebugDraw.removeMarker(MARKER_NAME); + * }, 5000); */ Q_INVOKABLE void addMarker(const QString& key, const glm::quat& rotation, const glm::vec3& position, const glm::vec4& color); /**jsdoc - * Removes debug marker from the world. Once a marker is removed, it will no longer be visible. + * Removes a debug marker that was added in world coordinates. * @function DebugDraw.removeMarker - * @param {string} key - name of marker to remove. + * @param {string} key - The name of the world coordinates debug marker to remove. */ Q_INVOKABLE void removeMarker(const QString& key); /**jsdoc - * Adds a debug marker to the world, this marker will be drawn every frame until it is removed with DebugDraw.removeMyAvatarMarker. - * This can be called repeatedly to change the position of the marker. + * Adds or updates a debug marker to the world in avatar coordinates. This marker is drawn every frame until it is removed + * using {@link DebugDraw.removeMyAvatarMarker|removeMyAvatarMarker}. If an avatar coordinates debug marker of the + * specified name already exists, its parameters are updated. The debug marker moves with your avatar. * @function DebugDraw.addMyAvatarMarker - * @param {string} key - name to uniquely identify this marker, later used for DebugDraw.removeMyAvatarMarker. - * @param {Quat} rotation - start position of line in avatar space. - * @param {Vec3} position - position of the marker in avatar space. + * @param {string} key - A name that uniquely identifies the marker. + * @param {Quat} rotation - The orientation of the marker in avatar coordinates. + * @param {Vec3} position - The position of the market in avatar coordinates. * @param {Vec4} color - color of the marker. + * @example Briefly draw a debug marker in front of your avatar, in avatar coordinates. + * var MARKER_NAME = "My avatar marker"; + * DebugDraw.addMyAvatarMarker( + * MARKER_NAME, + * Quat.ZERO, + * { x: 0, y: 0, z: -5 }, + * { red: 255, green: 0, blue: 0 } + * ); + * Script.setTimeout(function () { + * DebugDraw.removeMyAvatarMarker(MARKER_NAME); + * }, 5000); */ Q_INVOKABLE void addMyAvatarMarker(const QString& key, const glm::quat& rotation, const glm::vec3& position, const glm::vec4& color); /**jsdoc - * Removes debug marker from the world. Once a marker is removed, it will no longer be visible + * Removes a debug marker that was added in avatar coordinates. * @function DebugDraw.removeMyAvatarMarker - * @param {string} key - name of marker to remove. + * @param {string} key - The name of the avatar coordinates debug marker to remove. */ Q_INVOKABLE void removeMyAvatarMarker(const QString& key); diff --git a/libraries/shared/src/RegisteredMetaTypes.cpp b/libraries/shared/src/RegisteredMetaTypes.cpp index e23064c8a0..d6ce2f11b1 100644 --- a/libraries/shared/src/RegisteredMetaTypes.cpp +++ b/libraries/shared/src/RegisteredMetaTypes.cpp @@ -1229,8 +1229,10 @@ AnimationDetails::AnimationDetails(QString role, QUrl url, float fps, float prio * The details of an animation that is playing. * @typedef {object} Avatar.AnimationDetails * @property {string} role - Not used. - * @property {string} url - The URL to the animation file. Animation files need to be in .FBX format but only need to contain -* the avatar skeleton and animation data. + * @property {string} url - The URL to the animation file. Animation files need to be in glTF or FBX format but only need to + * contain the avatar skeleton and animation data. glTF models may be in JSON or binary format (".gltf" or ".glb" URLs + * respectively). + *

Warning: glTF animations currently do not always animate correctly.

* @property {number} fps - The frames per second(FPS) rate for the animation playback. 30 FPS is normal speed. * @property {number} priority - Not used. * @property {boolean} loop - true if the animation should loop, false if it shouldn't. 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} */ diff --git a/tools/jsdoc/plugins/hifi.js b/tools/jsdoc/plugins/hifi.js index a7c62cfc6d..67dafe5a16 100644 --- a/tools/jsdoc/plugins/hifi.js +++ b/tools/jsdoc/plugins/hifi.js @@ -56,6 +56,7 @@ exports.handlers = { '../../libraries/networking/src', '../../libraries/octree/src', '../../libraries/physics/src', + '../../libraries/platform/src/platform/backend', '../../libraries/plugins/src/plugins', '../../libraries/pointers/src', '../../libraries/render-utils/src',