Mirrors/overte-thingvellir
3
0
Fork 0
mirror of https://thingvellir.net/git/overte synced 2025-03-27 23:52:03 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #11791 from ctrlaltdavid/21602

Browse source 
JSDoc updates
This commit is contained in:
MiladNazeri 2017-12-12 12:18:02 -08:00 committed by GitHub
commit 16e16501cd
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
15 changed files with 440 additions and 140 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
interface/src/FancyCamera.h
View file

@ -19,10 +19,14 @@ class FancyCamera : public Camera {
Q_OBJECT
/**jsdoc
* @namespace Camera
* @property cameraEntity {EntityID} The position and rotation properties of
* the entity specified by this ID are then used as the camera's position and
* orientation. Only works when <code>mode</code> is "entity".
* @namespace
* @augments Camera
*/
// FIXME: JSDoc 3.5.5 doesn't augment @property definitions. The following definition is repeated in Camera.h.
/**jsdoc
* @property cameraEntity {Uuid} The ID of the entity that the camera position and orientation follow when the camera is in
* entity mode.
*/
Q_PROPERTY(QUuid cameraEntity READ getCameraEntity WRITE setCameraEntity)
@ -34,7 +38,25 @@ public:
public slots:
/**jsdoc
* Get the ID of the entity that the camera is set to use the position and orientation from when it's in entity mode. You can
* also get the entity ID using the <code>Camera.cameraEntity</code> property.
* @function Camera.getCameraEntity
* @returns {Uuid} The ID of the entity that the camera is set to follow when in entity mode; <code>null</code> if no camera
* entity has been set.
*/
QUuid getCameraEntity() const;
/**jsdoc
* Set the entity that the camera should use the position and orientation from when it's in entity mode. You can also set the
* entity using the <code>Camera.cameraEntity</code> property.
* @function Camera.setCameraEntity
* @param {Uuid} entityID The entity that the camera should follow when it's in entity mode.
* @example <caption>Move your camera to the position and orientation of the closest entity.</caption>
* Camera.setModeString("entity");
* var entity = Entities.findClosestEntity(MyAvatar.position, 100.0);
* Camera.setCameraEntity(entity);
*/
void setCameraEntity(QUuid entityID);
private:

4
interface/src/scripting/ClipboardScriptingInterface.cpp
View file

@ -34,7 +34,7 @@ bool ClipboardScriptingInterface::exportEntities(const QString& filename, const
return retVal;
}
bool ClipboardScriptingInterface::exportEntities(const QString& filename, float x, float y, float z, float s) {
bool ClipboardScriptingInterface::exportEntities(const QString& filename, float x, float y, float z, float scale) {
bool retVal;
BLOCKING_INVOKE_METHOD(qApp, "exportEntities",
Q_RETURN_ARG(bool, retVal),
@ -42,7 +42,7 @@ bool ClipboardScriptingInterface::exportEntities(const QString& filename, float
Q_ARG(float, x),
Q_ARG(float, y),
Q_ARG(float, z),
Q_ARG(float, s));
Q_ARG(float, scale));
return retVal;
}

46
interface/src/scripting/ClipboardScriptingInterface.h
View file

@ -18,6 +18,8 @@
#include <EntityItemID.h>
/**jsdoc
* The Clipboard API enables you to export and import entities to and from JSON files.
*
* @namespace Clipboard
*/
class ClipboardScriptingInterface : public QObject {
@ -25,48 +27,56 @@ class ClipboardScriptingInterface : public QObject {
public:
ClipboardScriptingInterface();
signals:
void readyToImport();
public:
/**jsdoc
* Compute the extents of the contents held in the clipboard.
* @function Clipboard.getContentsDimensions
* @return {Vec3} The extents of the contents held in the clipboard.
* @returns {Vec3} The extents of the contents held in the clipboard.
*/
Q_INVOKABLE glm::vec3 getContentsDimensions();
/**jsdoc
* Compute largest dimension of the extents of the contents held in the clipboard
* Compute the largest dimension of the extents of the contents held in the clipboard.
* @function Clipboard.getClipboardContentsLargestDimension
* @return {float} The largest dimension computed.
* @returns {number} The largest dimension computed.
*/
Q_INVOKABLE float getClipboardContentsLargestDimension();
/**jsdoc
* Import entities from a .json file containing entity data into the clipboard.
* You can generate * a .json file using {Clipboard.exportEntities}.
* Import entities from a JSON file containing entity data into the clipboard.
* You can generate a JSON file using {@link Clipboard.exportEntities}.
* @function Clipboard.importEntities
* @param {string} filename Filename of file to import.
* @return {bool} True if the import was succesful, otherwise false.
* @param {string} filename Path and name of file to import.
* @returns {boolean} <code>true</code> if the import was successful, otherwise <code>false</code>.
*/
Q_INVOKABLE bool importEntities(const QString& filename);
/**jsdoc
* Export the entities listed in `entityIDs` to the file `filename`
* Export the entities specified to a JSON file.
* @function Clipboard.exportEntities
* @param {string} filename Path to the file to export entities to.
* @param {EntityID[]} entityIDs IDs of entities to export.
* @return {bool} True if the export was succesful, otherwise false.
* @param {string} filename Path and name of the file to export the entities to. Should have the extension ".json".
* @param {Uuid[]} entityIDs Array of IDs of the entities to export.
* @returns {boolean} <code>true</code> if the export was successful, otherwise <code>false</code>.
*/
Q_INVOKABLE bool exportEntities(const QString& filename, const QVector<EntityItemID>& entityIDs);
Q_INVOKABLE bool exportEntities(const QString& filename, float x, float y, float z, float s);
/**jsdoc
* Export the entities with centers within a cube to a JSON file.
* @function Clipboard.exportEntities
* @param {string} filename Path and name of the file to export the entities to. Should have the extension ".json".
* @param {number} x X-coordinate of the cube center.
* @param {number} y Y-coordinate of the cube center.
* @param {number} z Z-coordinate of the cube center.
* @param {number} scale Half dimension of the cube.
* @returns {boolean} <code>true</code> if the export was successful, otherwise <code>false</code>.
*/
Q_INVOKABLE bool exportEntities(const QString& filename, float x, float y, float z, float scale);
/**jsdoc
* Paste the contents of the clipboard into the world.
* @function Clipboard.pasteEntities
* @param {Vec3} position Position to paste clipboard at.
* @return {EntityID[]} Array of entity IDs for the new entities that were
* created as a result of the paste operation.
* @param {Vec3} position Position to paste the clipboard contents at.
* @returns {Uuid[]} Array of entity IDs for the new entities that were created as a result of the paste operation.
*/
Q_INVOKABLE QVector<EntityItemID> pasteEntities(glm::vec3 position);
};

156
interface/src/scripting/MenuScriptingInterface.h
View file

@ -18,15 +18,18 @@
class MenuItemProperties;
/**jsdoc
* The `Menu` provides access to the menu that is shown at the top of the window
* shown on a user's desktop and the right click menu that is accessible
* in both Desktop and HMD mode.
* The Menu API provides access to the menu that is displayed at the top of the window
* on a user's desktop and in the tablet when the "MENU" button is pressed.
*
* <p />
*
* <h3>Groupings</h3>
* A `grouping` is a way to group a set of menus and/or menu items together
* so that they can all be set visible or invisible as a group. There are
* 2 available groups: "Advanced" and "Developer"
*
* A "grouping" provides a way to group a set of menus or menu items together so
* that they can all be set visible or invisible as a group.
* There are two available groups: <code>"Advanced"</code> and <code>"Developer"</code>.
* These groupings can be toggled in the "Settings" menu.
* If a menu item doesn't belong to a group it is always displayed.
*
* @namespace Menu
*/
@ -55,86 +58,113 @@ public slots:
/**jsdoc
* Add a new top-level menu.
* @function Menu.addMenu
* @param {string} menuName Name that will be shown in the menu.
* @param {string} grouping Name of the grouping to add this menu to.
* @param {string} menuName - Name that will be displayed for the menu. Nested menus can be described using the ">" symbol.
* @param {string} [grouping] - Name of the grouping, if any, to add this menu to.
*
* @example <caption>Add a menu and a nested submenu.</caption>
* Menu.addMenu("Test Menu");
* Menu.addMenu("Test Menu > Test Sub Menu");
*
* @example <caption>Add a menu to the Settings menu that is only visible if Settings > Advanced is enabled.</caption>
* Menu.addMenu("Settings > Test Grouping Menu", "Advanced");
*/
void addMenu(const QString& menuName, const QString& grouping = QString());
/**jsdoc
* Remove a top-level menu.
* @function Menu.removeMenu
* @param {string} menuName Name of the menu to remove.
* @param {string} menuName - Name of the menu to remove.
* @example <caption>Remove a menu and nested submenu.</caption>
* Menu.removeMenu("Test Menu > Test Sub Menu");
* Menu.removeMenu("Test Menu");
*/
void removeMenu(const QString& menuName);
/**jsdoc
* Check whether a top-level menu exists.
* @function Menu.menuExists
* @param {string} menuName Name of the menu to check for existence.
* @return {bool} `true` if the menu exists, otherwise `false`.
* @param {string} menuName - Name of the menu to check for existence.
* @returns {boolean} <code>true</code> if the menu exists, otherwise <code>false</code>.
* @example <caption>Check if the "Developer" menu exists.</caption>
* if (Menu.menuExists("Developer")) {
* print("Developer menu exists.");
* }
*/
bool menuExists(const QString& menuName);
/**jsdoc
* Add a separator with an unclickable label below it.
* The line will be placed at the bottom of the menu.
* Add a separator with an unclickable label below it. The separator will be placed at the bottom of the menu.
* If you want to add a separator at a specific point in the menu, use {@link Menu.addMenuItem} with
* {@link Menu.MenuItemProperties} instead.
* @function Menu.addSeparator
* @param {string} menuName Name of the menu to add a separator to.
* @param {string} separatorName Name of the separator that will be shown (but unclickable) below the separator line.
* @param {string} menuName - Name of the menu to add a separator to.
* @param {string} separatorName - Name of the separator that will be displayed as the label below the separator line.
* @example <caption>Add a separator.</caption>
* Menu.addSeparator("Developer","Test Separator");
*/
void addSeparator(const QString& menuName, const QString& separatorName);
/**jsdoc
* Remove a separator and its label from a menu.
* Remove a separator from a menu.
* @function Menu.removeSeparator
* @param {string} menuName Name of the menu to remove a separator from.
* @param {string} separatorName Name of the separator to remove.
* @param {string} menuName - Name of the menu to remove the separator from.
* @param {string} separatorName - Name of the separator to remove.
* @example <caption>Remove a separator.</caption>
* Menu.removeSeparator("Developer","Test Separator");
*/
void removeSeparator(const QString& menuName, const QString& separatorName);
/**jsdoc
* Add a new menu item to a menu.
* @function Menu.addMenuItem
* @param {Menu.MenuItemProperties} properties
* @param {Menu.MenuItemProperties} properties - Properties of the menu item to create.
* @example <caption>Add a menu item using {@link Menu.MenuItemProperties}.</caption>
* Menu.addMenuItem({
* menuName: "Developer",
* menuItemName: "Test",
* afterItem: "Log",
* shortcutKey: "Ctrl+Shift+T",
* grouping: "Advanced"
* });
*/
void addMenuItem(const MenuItemProperties& properties);
/**jsdoc
* Add a new menu item to a menu.
* Add a new menu item to a menu. The new item is added at the end of the menu.
* @function Menu.addMenuItem
* @param {string} menuName Name of the menu to add a menu item to.
* @param {string} menuItem Name of the menu item. This is what will be displayed in the menu.
* @param {string} shortcutKey A shortcut key that can be used to trigger the menu item.
* @param {string} menuName - Name of the menu to add a menu item to.
* @param {string} menuItem - Name of the menu item. This is what will be displayed in the menu.
* @param {string} [shortcutKey] A shortcut key that can be used to trigger the menu item.
* @example <caption>Add a menu item to the end of the "Developer" menu.</caption>
* Menu.addMenuItem("Developer", "Test", "Ctrl+Shift+T");
*/
void addMenuItem(const QString& menuName, const QString& menuitem, const QString& shortcutKey);
/**jsdoc
* Add a new menu item to a menu.
* @function Menu.addMenuItem
* @param {string} menuName Name of the menu to add a menu item to.
* @param {string} menuItem Name of the menu item. This is what will be displayed in the menu.
*/
void addMenuItem(const QString& menuName, const QString& menuitem);
/**jsdoc
* Remove a menu item from a menu.
* @function Menu.removeMenuItem
* @param {string} menuName Name of the menu to remove a menu item from.
* @param {string} menuItem Name of the menu item to remove.
* @param {string} menuName - Name of the menu to remove a menu item from.
* @param {string} menuItem - Name of the menu item to remove.
* Menu.removeMenuItem("Developer", "Test");
*/
void removeMenuItem(const QString& menuName, const QString& menuitem);
/**jsdoc
* Check if a menu item exists.
* @function Menu.menuItemExists
* @param {string} menuName Name of the menu that the menu item is in.
* @param {string} menuItem Name of the menu item to check for existence of.
* @return {bool} `true` if the menu item exists, otherwise `false`.
* @param {string} menuName - Name of the menu that the menu item is in.
* @param {string} menuItem - Name of the menu item to check for existence of.
* @returns {boolean} <code>true</code> if the menu item exists, otherwise <code>false</code>.
* @example <caption>Determine if the Developer &gt; Stats menu exists.</caption>
* if (Menu.menuItemExists("Developer", "Stats")) {
* print("Developer > Stats menu item exists.");
* }
*/
bool menuItemExists(const QString& menuName, const QString& menuitem);
/**
* Not working, will not document until fixed
* TODO: Not working; don't document until fixed.
*/
void addActionGroup(const QString& groupName, const QStringList& actionList,
const QString& selected = QString());
@ -143,53 +173,73 @@ public slots:
/**jsdoc
* Check whether a checkable menu item is checked.
* @function Menu.isOptionChecked
* @param {string} menuOption The name of the menu item.
* @return `true` if the option is checked, otherwise false.
* @param {string} menuOption - The name of the menu item.
* @returns {boolean} <code>true</code> if the option is checked, otherwise <code>false</code>.
* @example <caption>Report whether the Settings > Advanced menu item is turned on.</caption>
* print(Menu.isOptionChecked("Advanced Menus")); // true or false
*/
bool isOptionChecked(const QString& menuOption);
/**jsdoc
* Set a checkable menu item as checked or unchecked.
* @function Menu.setIsOptionChecked
* @param {string} menuOption The name of the menu item to modify.
* @param {bool} isChecked If `true`, the menu item will be checked, otherwise it will not be checked.
* @param {string} menuOption - The name of the menu item to modify.
* @param {boolean} isChecked - If <code>true</code>, the menu item will be checked, otherwise it will not be checked.
* @example <caption>Turn on Settings > Advanced Menus.</caption>
* Menu.setIsOptionChecked("Advanced Menus", true);
* print(Menu.isOptionChecked("Advanced Menus")); // true
*/
void setIsOptionChecked(const QString& menuOption, bool isChecked);
/**jsdoc
* Toggle the status of a checkable menu item. If it is checked, it will be unchecked.
* If it is unchecked, it will be checked.
* @function Menu.setIsOptionChecked
* @param {string} menuOption The name of the menu item to toggle.
* Trigger the menu item as if the user clicked on it.
* @function Menu.triggerOption
* @param {string} menuOption - The name of the menu item to trigger.
* @example <caption>Open the help window.</caption>
* Menu.triggerOption('Help...');
*/
void triggerOption(const QString& menuOption);
/**jsdoc
* Check whether a menu is enabled. If a menu is disabled it will be greyed out
* and unselectable.
* Check whether a menu or menu item is enabled. If disabled, the item is grayed out and unusable.
* Menus are enabled by default.
* @function Menu.isMenuEnabled
* @param {string} menuName The name of the menu to check.
* @return {bool} `true` if the menu is enabled, otherwise false.
* @param {string} menuName The name of the menu or menu item to check.
* @returns {boolean} <code>true</code> if the menu is enabled, otherwise <code>false</code>.
* @example <caption>Report with the Settings > Advanced Menus menu item is enabled.</caption>
* print(Menu.isMenuEnabled("Settings > Advanced Menus")); // true or false
*/
bool isMenuEnabled(const QString& menuName);
/**jsdoc
* Set a menu to be enabled or disabled.
* Set a menu or menu item to be enabled or disabled. If disabled, the item is grayed out and unusable.
* @function Menu.setMenuEnabled
* @param {string} menuName The name of the menu to modify.
* @param {bool} isEnabled Whether the menu will be enabled or not.
* @param {string} menuName - The name of the menu or menu item to modify.
* @param {boolean} isEnabled - If <code>true</code>, the menu will be enabled, otherwise it will be disabled.
* @example <caption>Disable the Settings > Advanced Menus menu item.</caption>
* Menu.setMenuEnabled("Settings > Advanced Menus", false);
* print(Menu.isMenuEnabled("Settings > Advanced Menus")); // false
*/
void setMenuEnabled(const QString& menuName, bool isEnabled);
/**
* TODO: Not used or useful; will not document until used.
*/
void closeInfoView(const QString& path);
bool isInfoViewVisible(const QString& path);
signals:
/**jsdoc
* This is a signal that is emitted when a menu item is clicked.
* Triggered when a menu item is clicked (or triggered by {@link Menu.triggerOption}).
* @function Menu.menuItemEvent
* @param {string} menuItem Name of the menu item that was triggered.
* @param {string} menuItem - Name of the menu item that was clicked.
* @returns {Signal}
* @example <caption>Detect menu item events.</caption>
* function onMenuItemEvent(menuItem) {
* print("You clicked on " + menuItem);
* }
*
* Menu.menuItemEvent.connect(onMenuItemEvent);
*/
void menuItemEvent(const QString& menuItem);
};

30
libraries/script-engine/src/MenuItemProperties.cpp
View file

@ -51,22 +51,24 @@ QScriptValue menuItemPropertiesToScriptValue(QScriptEngine* engine, const MenuIt
}
/**jsdoc
* `MenuItemProperties` is a list of properties that can be passed to Menu.addMenuItem
* to create a new menu item.
* A set of properties that can be passed to {@link Menu.addMenuItem} to create a new menu item.
*
* If none of position, beforeItem, afterItem, or grouping are specified, the
* menu item will be placed in the last position.
* If none of <code>position</code>, <code>beforeItem</code>, <code>afterItem</code>, or <code>grouping</code> are specified,
* the menu item will be placed at the end of the menu.
*
* @typedef {Object} Menu.MenuItemProperties
* @property {string} menuName Name of the top-level menu
* @property {string} menuItemName Name of the menu item
* @property {bool} isCheckable Whether the menu item is checkable or not
* @property {bool} isChecked Where the menu item is checked or not
* @property {string} shortcutKey An optional shortcut key to trigger the menu item.
* @property {int} position The position to place the new menu item. `0` is the first menu item.
* @property {string} beforeItem The name of the menu item to place this menu item before.
* @property {string} afterItem The name of the menu item to place this menu item after.
* @property {string} grouping The name of grouping to add this menu item to.
* @typedef {object} Menu.MenuItemProperties
* @property {string} menuName Name of the menu. Nested menus can be described using the ">" symbol.
* @property {string} menuItemName Name of the menu item.
* @property {boolean} [isCheckable=false] Whether or not the menu item is checkable.
* @property {boolean} [isChecked=false] Whether or not the menu item is checked.
* @property {boolean} [isSeparator=false] Whether or not the menu item is a separator.
* @property {string} [shortcutKey] A shortcut key that triggers the menu item.
* @property {KeyEvent} [shortcutKeyEvent] A {@link KeyEvent} that specifies a key that triggers the menu item.
* @property {number} [position] The position to place the new menu item. An integer number with <code>0</code> being the first
* menu item.
* @property {string} [beforeItem] The name of the menu item to place this menu item before.
* @property {string} [afterItem] The name of the menu item to place this menu item after.
* @property {string} [grouping] The name of grouping to add this menu item to.
*/
void menuItemPropertiesFromScriptValue(const QScriptValue& object, MenuItemProperties& properties) {
properties.menuName = object.property("menuName").toVariant().toString();

2
libraries/script-engine/src/Quat.h
View file

@ -23,7 +23,7 @@
/**jsdoc
* A Quaternion
*
* @typedef Quat
* @typedef {object} Quat
* @property {float} x imaginary component i.
* @property {float} y imaginary component j.
* @property {float} z imaginary component k.

83
libraries/script-engine/src/ScriptUUID.h
View file

@ -17,17 +17,100 @@
#include <QUuid>
#include <QtScript/QScriptable>
/**jsdoc
* A UUID (Universally Unique IDentifier) is used to uniquely identify entities, overlays, avatars, and the like. It is
* represented in JavaScript as a string in the format, <code>{nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}</code>, where the "n"s are
* hexadecimal digits.
*
* @namespace Uuid
* @property NULL {Uuid} The null UUID, <code>{00000000-0000-0000-0000-000000000000}</code>.
*/
/// Scriptable interface for a UUID helper class object. Used exclusively in the JavaScript API
class ScriptUUID : public QObject, protected QScriptable {
Q_OBJECT
Q_PROPERTY(QString NULL READ NULL_UUID CONSTANT) // String for use in scripts.
public slots:
/**jsdoc
* Generates a UUID from a string representation of the UUID.
* @function Uuid.fromString
* @param {string} string - A string representation of a UUID. The curly braces are optional.
* @returns {Uuid} A UUID if the given <code>string</code> is valid, <code>null</code> otherwise.
* @example <caption>Valid and invalid parameters.</caption>
* var uuid = Uuid.fromString("{527c27ea-6d7b-4b47-9ae2-b3051d50d2cd}");
* print(uuid); // {527c27ea-6d7b-4b47-9ae2-b3051d50d2cd}
*
* uuid = Uuid.fromString("527c27ea-6d7b-4b47-9ae2-b3051d50d2cd");
* print(uuid); // {527c27ea-6d7b-4b47-9ae2-b3051d50d2cd}
*
* uuid = Uuid.fromString("527c27ea");
* print(uuid); // null
*/
QUuid fromString(const QString& string);
/**jsdoc
* Generates a string representation of a UUID. However, because UUIDs are represented in JavaScript as strings, this is in
* effect a no-op.
* @function Uuid.toString
* @param {Uuid} id - The UUID to generate a string from.
* @returns {string} - A string representation of the UUID.
*/
QString toString(const QUuid& id);
/**jsdoc
* Generate a new UUID.
* @function Uuid.generate
* @returns {Uuid} A new UUID.
* @example <caption>Generate a new UUID and reports its JavaScript type.</caption>
* var uuid = Uuid.generate();
* print(uuid); // {nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}
* print(typeof uuid); // string
*/
QUuid generate();
/**jsdoc
* Test whether two given UUIDs are equal.
* @function Uuid.isEqual
* @param {Uuid} idA - The first UUID to compare.
* @param {Uuid} idB - The second UUID to compare.
* @returns {boolean} <code>true</code> if the two UUIDs are equal, otherwise <code>false</code>.
* @example <caption>Demonstrate <code>true</code> and <code>false</code> cases.</caption>
* var uuidA = Uuid.generate();
* var uuidB = Uuid.generate();
* print(Uuid.isEqual(uuidA, uuidB)); // false
* uuidB = uuidA;
* print(Uuid.isEqual(uuidA, uuidB)); // true
*/
bool isEqual(const QUuid& idA, const QUuid& idB);
/**jsdoc
* Test whether a given UUID is null.
* @function Uuid.isNull
* @param {Uuid} id - The UUID to test.
* @returns {boolean} <code>true</code> if the UUID equals Uuid.NULL or is <code>null</code>, otherwise <code>false</code>.
* @example <caption>Demonstrate <code>true</code> and <code>false</code> cases.</caption>
* var uuid; // undefined
* print(Uuid.isNull(uuid)); // false
* uuid = Uuid.generate();
* print(Uuid.isNull(uuid)); // false
* uuid = Uuid.NULL;
* print(Uuid.isNull(uuid)); // true
* uuid = null;
* print(Uuid.isNull(uuid)); // true
*/
bool isNull(const QUuid& id);
/**jsdoc
* Print to the program log a text label followed by the UUID value.
* @function Uuid.print
* @param {string} label - The label to print.
* @param {Uuid} id - The UUID to print.
* @example <caption>Two ways of printing a label plus UUID.</caption>
* var uuid = Uuid.generate();
* Uuid.print("Generated UUID:", uuid); // Generated UUID: {nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}
* print("Generated UUID: " + uuid); // Generated UUID: {nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn}
*/
void print(const QString& label, const QUuid& id);
private:

6
libraries/script-engine/src/Vec3.h
View file

@ -24,7 +24,7 @@
/**jsdoc
* A 2-dimensional vector.
*
* @typedef Vec2
* @typedef {object} Vec2
* @property {float} x X-coordinate of the vector.
* @property {float} y Y-coordinate of the vector.
*/
@ -32,7 +32,7 @@
/**jsdoc
* A 3-dimensional vector.
*
* @typedef Vec3
* @typedef {object} Vec3
* @property {float} x X-coordinate of the vector.
* @property {float} y Y-coordinate of the vector.
* @property {float} z Z-coordinate of the vector.
@ -41,7 +41,7 @@
/**jsdoc
* A 4-dimensional vector.
*
* @typedef Vec4
* @typedef {object} Vec4
* @property {float} x X-coordinate of the vector.
* @property {float} y Y-coordinate of the vector.
* @property {float} z Z-coordinate of the vector.

6
libraries/shared/src/PathUtils.h
View file

@ -19,9 +19,13 @@
#include "DependencyManager.h"
/**jsdoc
* The Paths API provides absolute paths to the scripts and resources directories.
*
* @namespace Paths
* @deprecated The Paths API is deprecated. Use {@link Script.resolvePath} and {@link Script.resourcesPath} instead.
* @readonly
* @property {string} resources The path to the resources directory.
* @property {string} defaultScripts - The path to the scripts directory. <em>Read-only.</em>
* @property {string} resources - The path to the resources directory. <em>Read-only.</em>
*/
class PathUtils : public QObject, public Dependency {
Q_OBJECT

39
libraries/shared/src/RegisteredMetaTypes.h
View file

@ -134,15 +134,16 @@ public:
virtual QVariantMap toVariantMap() const = 0;
};
/**jsdoc
* A PickRay defines a vector with a starting point. It is used, for example, when finding entities or overlays that lie under a
* mouse click or intersect a laser beam.
*
* @typedef {object} PickRay
* @property {Vec3} origin - The starting position of the PickRay.
* @property {Quat} direction - The direction that the PickRay travels.
*/
class PickRay : public MathPick {
public:
/**jsdoc
* The mathematical definition of a ray.
*
* @typedef {Object} PickRay
* @property {Vec3} origin The origin of the ray.
* @property {Vec3} direction The direction of the ray.
*/
PickRay() : origin(NAN), direction(NAN) { }
PickRay(const QVariantMap& pickVariant) : origin(vec3FromVariant(pickVariant["origin"])), direction(vec3FromVariant(pickVariant["direction"])) {}
PickRay(const glm::vec3& origin, const glm::vec3 direction) : origin(origin), direction(direction) {}
@ -166,17 +167,17 @@ Q_DECLARE_METATYPE(PickRay)
QScriptValue pickRayToScriptValue(QScriptEngine* engine, const PickRay& pickRay);
void pickRayFromScriptValue(const QScriptValue& object, PickRay& pickRay);
/**jsdoc
* A StylusTip defines the tip of a stylus.
*
* @typedef {object} StylusTip
* @property {number} side - The hand the tip is attached to: <code>0</code> for left, <code>1</code> for right.
* @property {Vec3} position - The position of the stylus tip.
* @property {Quat} orientation - The orientation of the stylus tip.
* @property {Vec3} velocity - The velocity of the stylus tip.
*/
class StylusTip : public MathPick {
public:
/**jsdoc
* The mathematical definition of a stylus tip.
*
* @typedef {Object} StylusTip
* @property {number} side The hand the tip is attached to. 0 == left, 1 == right.
* @property {Vec3} position The position of the tip.
* @property {Quat} orientation The orientation of the tip.
* @property {Vec3} velocity The velocity of the tip.
*/
StylusTip() : position(NAN), velocity(NAN) {}
StylusTip(const QVariantMap& pickVariant) : side(bilateral::Side(pickVariant["side"].toInt())), position(vec3FromVariant(pickVariant["position"])),
orientation(quatFromVariant(pickVariant["orientation"])), velocity(vec3FromVariant(pickVariant["velocity"])) {}
@ -208,9 +209,9 @@ namespace std {
template <typename T, typename... Rest>
inline void hash_combine(std::size_t& seed, const T& v, Rest... rest) {
std::hash<T> hasher;
seed ^= hasher(v) + 0x9e3779b9 + (seed<<6) + (seed>>2);
hash_combine(seed, rest...);
std::hash<T> hasher;
seed ^= hasher(v) + 0x9e3779b9 + (seed<<6) + (seed>>2);
hash_combine(seed, rest...);
}
template <>

3
libraries/shared/src/ViewFrustum.h
View file

@ -33,9 +33,6 @@ const float DEFAULT_ASPECT_RATIO = 16.0f/9.0f;
const float DEFAULT_NEAR_CLIP = 0.08f;
const float DEFAULT_FAR_CLIP = 16384.0f;
// the "ViewFrustum" has a "keyhole" shape: a regular frustum for stuff that is "visible" with
// a central sphere for stuff that is nearby (for physics simulation).
class ViewFrustum {
public:
// setters for camera attributes

58
libraries/shared/src/shared/Camera.cpp
View file

@ -10,6 +10,52 @@
#include "Camera.h"
/**jsdoc
* <p>Camera modes affect the position of the camera and the controls for camera movement. The camera can be in one of the
* following modes:</p>
* <table>
* <thead>
* <tr>
* <th>Mode</th>
* <th>String</th>
* <th>Description</th>
* </tr>
* </thead>
* <tbody>
* <tr>
* <td><strong>First&nbsp;Person</strong></td>
* <td><code>"first&nbsp;person"</code></td>
* <td>The camera is positioned such that you have the same view as your avatar. The camera moves and rotates with your
* avatar.</td>
* </tr>
* <tr>
* <td><strong>Third&nbsp;Person</strong></td>
* <td><code>"third&nbsp;person"</code></td>
* <td>The camera is positioned such that you have a view from just behind your avatar. The camera moves and rotates with
* your avatar.</td>
* </tr>
* <tr>
* <td><strong>Mirror</strong></td>
* <td><code>"mirror"</code></td>
* <td>The camera is positioned such that you are looking directly at your avatar. The camera moves and rotates with your
* avatar.</td>
* </tr>
* <tr>
* <td><strong>Independent</strong></td>
* <td><code>"independent"</code></td>
* <td>The camera's position and orientation don't change with your avatar movement. Instead, they can be set via
* scripting.</td>
* </tr>
* <tr>
* <td><strong>Entity</strong></td>
* <td><code>"entity"</code></td>
* <td>The camera's position and orientation are set to be the same as a specified entity's, and move with the entity as
* it moves.
* </tr>
* </tbody>
* </table>
* @typedef {string} Camera.Mode
*/
CameraMode stringToMode(const QString& mode) {
if (mode == "third person") {
return CAMERA_MODE_THIRD_PERSON;
@ -131,6 +177,18 @@ void Camera::loadViewFrustum(ViewFrustum& frustum) const {
frustum.calculate();
}
/**jsdoc
* A ViewFrustum has a "keyhole" shape: a regular frustum for stuff that is visible plus a central sphere for stuff that is
* nearby (for physics simulation).
*
* @typedef {object} ViewFrustum
* @property {Vec3} position - The location of the frustum's apex.
* @property {Quat} orientation - The direction that the frustum is looking at.
* @property {number} centerRadius - Center radius of the keyhole in meters.
* @property {number} fieldOfView - Horizontal field of view in degrees.
* @property {number} aspectRatio - Aspect ratio of the frustum.
* @property {Mat4} projection - The projection matrix for the view defined by the frustum.
*/
QVariantMap Camera::getViewFrustum() {
ViewFrustum frustum;
loadViewFrustum(frustum);

108
libraries/shared/src/shared/Camera.h
View file

@ -37,12 +37,18 @@ class Camera : public QObject {
Q_OBJECT
/**jsdoc
* The Camera API provides access to the "camera" that defines your view in desktop and HMD display modes.
*
* @namespace Camera
* @property position {Vec3} The position of the camera.
* @property orientation {Quat} The orientation of the camera.
* @property mode {string} The current camera mode.
* @property frustum {Object} The frustum of the camera.
* @property position {Vec3} The position of the camera. You can set this value only when the camera is in independent mode.
* @property orientation {Quat} The orientation of the camera. You can set this value only when the camera is in independent
* mode.
* @property mode {Camera.Mode} The camera mode.
* @property frustum {ViewFrustum} The camera frustum.
* @property cameraEntity {Uuid} The ID of the entity that is used for the camera position and orientation when the camera
* is in entity mode.
*/
// FIXME: The cameraEntity property definition is copied from FancyCamera.h.
Q_PROPERTY(glm::vec3 position READ getPosition WRITE setPosition)
Q_PROPERTY(glm::quat orientation READ getOrientation WRITE setOrientation)
Q_PROPERTY(QString mode READ getModeString WRITE setModeString)
@ -69,52 +75,118 @@ public:
QVariantMap getViewFrustum();
public slots:
/**jsdoc
* Get the current camera mode. You can also get the mode using the <code>Camera.mode</code> property.
* @function Camera.getModeString
* @returns {Camera.Mode} The current camera mode.
*/
QString getModeString() const;
/**jsdoc
* Set the camera mode. You can also set the mode using the <code>Camera.mode</code> property.
* @function Camera.setModeString
* @param {Camera.Mode} mode - The mode to set the camera to.
*/
void setModeString(const QString& mode);
/**jsdoc
* Get the current camera position. You can also get the position using the <code>Camera.position</code> property.
* @function Camera.getPosition
* @returns {Vec3} The current camera position.
*/
glm::vec3 getPosition() const { return _position; }
/**jsdoc
* Set the camera position. You can also set the position using the <code>Camera.position</code> property. Only works if the
* camera is in independent mode.
* @function Camera.setPosition
* @param {Vec3} position - The position to set the camera at.
*/
void setPosition(const glm::vec3& position);
/**jsdoc
* Get the current camera orientation. You can also get the orientation using the <code>Camera.orientation</code> property.
* @function Camera.getOrientation
* @returns {Quat} The current camera orientation.
*/
glm::quat getOrientation() const { return _orientation; }
/**jsdoc
* Set the camera orientation. You can also set the orientation using the <code>Camera.orientation</code> property. Only
* works if the camera is in independent mode.
* @function Camera.setOrientation
* @param {Quat} orientation - The orientation to set the camera to.
*/
void setOrientation(const glm::quat& orientation);
/**jsdoc
* Compute a {PickRay} based on the current camera configuration and the position x,y on the screen.
* Compute a {@link PickRay} based on the current camera configuration and the specified <code>x, y</code> position on the
* screen. The {@link PickRay} can be used in functions such as {@link Entities.findRayIntersection} and
* {@link Overlays.findRayIntersection}.
* @function Camera.computePickRay
* @param {float} x X-coordinate on screen.
* @param {float} y Y-coordinate on screen.
* @return {PickRay} The computed {PickRay}.
* @param {number} x - X-coordinate on screen.
* @param {number} y - Y-coordinate on screen.
* @returns {PickRay} The computed {@link PickRay}.
* @example <caption>Use a PickRay to detect mouse clicks on entities.</caption>
* function onMousePressEvent(event) {
* var pickRay = Camera.computePickRay(event.x, event.y);
* var intersection = Entities.findRayIntersection(pickRay);
* if (intersection.intersects) {
* print ("You clicked on entity " + intersection.entityID);
* }
* }
*
* Controller.mousePressEvent.connect(onMousePressEvent);
*/
virtual PickRay computePickRay(float x, float y) const = 0;
/**jsdoc
* Set the camera to look at position <code>position</code>. Only works while in <code>independent</code>.
* camera mode.
* Rotate the camera to look at the specified <code>position</code>. Only works if the camera is in independent mode.
* @function Camera.lookAt
* @param {Vec3} Position Position to look at.
* @param {Vec3} position - Position to look at.
* @example <caption>Rotate your camera to look at entities as you click on them with your mouse.</caption>
* function onMousePressEvent(event) {
* var pickRay = Camera.computePickRay(event.x, event.y);
* var intersection = Entities.findRayIntersection(pickRay);
* if (intersection.intersects) {
* // Switch to independent mode.
* Camera.mode = "independent";
* // Look at the entity that was clicked.
* var properties = Entities.getEntityProperties(intersection.entityID, "position");
* Camera.lookAt(properties.position);
* }
* }
*
* Controller.mousePressEvent.connect(onMousePressEvent);
*/
void lookAt(const glm::vec3& position);
/**jsdoc
* Set the camera to continue looking at position <code>position</code>.
* Only works while in `independent` camera mode.
* Set the camera to continue looking at the specified <code>position</code> even while the camera moves. Only works if the
* camera is in independent mode.
* @function Camera.keepLookingAt
* @param {Vec3} position Position to keep looking at.
* @param {Vec3} position - Position to keep looking at.
*/
void keepLookingAt(const glm::vec3& position);
/**jsdoc
* Stops the camera from continually looking at a position that was set with
* `keepLookingAt`
* Stops the camera from continually looking at the position that was set with <code>Camera.keepLookingAt</code>.
* @function Camera.stopLookingAt
*/
void stopLooking() { _isKeepLookingAt = false; }
signals:
/**jsdoc
* Triggered when camera mode has changed.
* Triggered when the camera mode changes.
* @function Camera.modeUpdated
* @return {Signal}
* @param {Camera.Mode} newMode - The new camera mode.
* @returns {Signal}
* @example <caption>Report camera mode changes.</caption>
* function onCameraModeUpdated(newMode) {
* print("The camera mode has changed to " + newMode);
* }
*
* Camera.modeUpdated.connect(onCameraModeUpdated);
*/
void modeUpdated(const QString& newMode);

8
tools/jsdoc/README.md
View file

@ -5,9 +5,9 @@
* Install node.js
* Install jsdoc via npm. `npm install jsdoc -g`
To generate html documentation for the High Fidelity JavaScript API
To generate html documentation for the High Fidelity JavaScript API:
`cd scripts/jsdoc`
`jsdoc . -c config.json`
* `cd tools/jsdoc`
* `jsdoc . -c config.json`
The out folder should contain index.html
The out folder should contain index.html.

1
tools/jsdoc/plugins/hifi.js
View file

@ -26,6 +26,7 @@ exports.handlers = {
'../../libraries/networking/src',
'../../libraries/pointers/src',
'../../libraries/shared/src',
'../../libraries/shared/src/shared',
'../../libraries/script-engine/src',
];
var exts = ['.h', '.cpp'];