Merge pull request #15988 from ctrlaltdavid/DOC-98

DOC-98, DOC-114: PlatformInfo API changes JSDoc
This commit is contained in:
Shannon Romano 2019-08-06 13:22:36 -07:00 committed by GitHub
commit 93d5d9bd3f
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 249 additions and 96 deletions

View file

@ -15,7 +15,7 @@
class QScriptValue;
/**jsdoc
* The <code>PlatformInfo</code> API provides information about the computer and controllers being used.
* The <code>PlatformInfo</code> API provides information about the hardware platform being used.
*
* @namespace PlatformInfo
*
@ -31,6 +31,21 @@ public:
PlatformInfoScriptingInterface();
virtual ~PlatformInfoScriptingInterface();
/**jsdoc
* <p>The platform tier of a computer is an indication of its rendering capability.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Name</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>0</code></td><td>UNKNOWN</td><td>Unknown rendering capability.</td></tr>
* <tr><td><code>1</code></td><td>LOW</td><td>Low-end PC, capable of rendering low-quality graphics.</td></tr>
* <tr><td><code>2</code></td><td>MID</td><td>Business-class PC, capable of rendering medium-quality graphics.</td></tr>
* <tr><td><code>3</code></td><td>HIGH</td><td>High-end PC, capable of rendering high-quality graphics.</td></tr>
* </tbody>
* </table>
* @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} <code>"WINDOWS"</code>, <code>"MACOS"</code>, or <code>"UNKNOWN"</code>.
* @returns {string} The operating system type: <code>"WINDOWS"</code>, <code>"MACOS"</code>, or <code>"UNKNOWN"</code>.
* @deprecated This function is deprecated and will be removed.
* use getComputer()["OS"] instead
* Use <code>JSON.parse({@link PlatformInfo.getComputer|PlatformInfo.getComputer()}).OS</code> 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 <caption>Report the CPU being used.</caption>
* 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 <code>JSON.parse({@link PlatformInfo.getCPU|PlatformInfo.getCPU(0)}).model</code> 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 <code>JSON.parse({@link PlatformInfo.getCPU|PlatformInfo.getCPU(0)}).numCores</code> 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 <code>JSON.parse({@link PlatformInfo.getMemory|PlatformInfo.getMemory()}).memTotal</code> 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 <code>JSON.parse({@link PlatformInfo.getGPU|PlatformInfo.getGPU(}
* {@link PlatformInfo.getMasterGPU|PlatformInfo.getMasterGPU() )}).model</code>
* 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} <code>true</code> if the current display supports HTML on 3D surfaces, <code>false</code> 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} <code>true</code> if Interface is running on a stand-alone device, <code>false</code> if it isn't.
* @returns {boolean} <code>true</code> if Interface is running on a stand-alone HMD device, <code>false</code> 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 <caption>Report details of the computer's CPUs.</caption>
* 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 <caption>Report details of the computer's GPUs.</caption>
* 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 <caption>Report details of the systems's displays.</caption>
* 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 <caption>Report details of the computer's memory.</caption>
* 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 <caption>Report the platform tier of the computer.</caption>
* 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} <code>true</code> if the current hardware can render using the Deferred method; <code>false</code> otherwise.
*/
* Gets whether the current hardware can use deferred rendering.
* @function PlatformInfo.isRenderMethodDeferredCapable
* @returns {boolean} <code>true</code> if the current hardware can use deferred rendering, <code>false</code> if it can't.
*/
bool isRenderMethodDeferredCapable();
};

View file

@ -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., <code>"Intel"</code> or <code>"AMD"</code>).
* @property {string} model - The CPU model.
* @property {number} numCores - The number of logical cores.
* @property {boolean} isMaster - <code>true</code> if the CPU is the "master" or primary CPU, <code>false</code> or
* <code>undefined</code> 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., <code>"NVIDIA"</code>, <code>"AMD"</code>, or <code>"Intel"</code>).
* @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 - <code>true</code> if the GPU is the "master" or primary GPU, <code>false</code> or
* <code>undefined</code> 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., <code>0</code>).
* @property {number} boundsRight - The pixel coordinate of the right edge of the display (e.g., <code>1920</code>).
* @property {number} boundsTop - The pixel coordinate of the top edge of the display (e.g., <code>0</code>).
* @property {number} boundsBottom - The pixel coordinate of the bottom edge of the display (e.g., <code>1080</code>).
* @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 - <code>true</code> if the GPU is the "master" or primary display, <code>false</code> or
* <code>undefined</code> 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
* <p>The computer operating system.</p>
* <table>
* <thead>
* <tr><th>Value</th><th>Description</th></tr>
* </thead>
* <tbody>
* <tr><td><code>"WINDOWS"</code></td><td>Windows.</td></tr>
* <tr><td><code>"MACOS"</code></td><td>Mac OS.</td></tr>
* <tr><td><code>"LINUX"</code></td><td>Linux.</td></tr>
* <tr><td><code>"ANDROID"</code></td><td>Android.</td></tr>
* </tbody>
* </table>
* @typedef {string} PlatformInfo.ComputerOS
*/
namespace computer {
const char* OS = "OS";
const char* OS_WINDOWS = "WINDOWS";

View file

@ -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',