diff --git a/interface/src/scripting/PlatformInfoScriptingInterface.h b/interface/src/scripting/PlatformInfoScriptingInterface.h index f59d476f0c..8bb510832a 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 graphics 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 in the hardware platform. + * @function PlatformInfo.getNumCPUs + * @returns {number} The number of CPUs in the hardware platform. + */ 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 in the hardware platform. + */ 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 in the hardware platform. + * @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 in the hardware platform. * @function PlatformInfo.getNumGPUs - * @returns {number} The number of GPUs detected on the hardware platform. + * @returns {number} The number of GPUs in the hardware platform. */ 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 detected in the hardware platform. + */ 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 in the hardware platform. * @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 in the hardware platform. + * @function PlatformInfo.getNumDisplays + * @returns {number} The number of displays in the hardware platform. + */ 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 in the hardware platform. + */ 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 in the hardware platform. + * @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 hardware platform. + * @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/libraries/platform/src/platform/backend/Platform.cpp b/libraries/platform/src/platform/backend/Platform.cpp index 17d9d8019e..89248ddefa 100644 --- a/libraries/platform/src/platform/backend/Platform.cpp +++ b/libraries/platform/src/platform/backend/Platform.cpp @@ -10,19 +10,51 @@ #include "../Platform.h" #include "../PlatformKeys.h" +/**jsdoc + * Information on the hardware platform. + * @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.MemoryDescription} memory - Information on the computers memory. + * @property {PlatformInfo.NICDescription} nics - Information on the computers 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,10 +67,38 @@ namespace platform { namespace keys { const char* displays = "displays"; const char* isMaster = "isMaster"; } + + /**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 GPU, false or + * undefined if it isn't. + */ namespace display { const char* description = "description"; const char* name = "deviceName"; @@ -56,9 +116,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
"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/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',