From 39ccd7d65647754fd78b86859c21faf1b9a738f6 Mon Sep 17 00:00:00 2001 From: David Rowe Date: Sun, 12 Nov 2017 11:04:35 +1300 Subject: [PATCH] Update JSDoc for Camera API --- interface/src/FancyCamera.h | 30 +++++- libraries/shared/src/shared/Camera.h | 154 ++++++++++++++++++++++++--- tools/jsdoc/plugins/hifi.js | 1 + 3 files changed, 165 insertions(+), 20 deletions(-) diff --git a/interface/src/FancyCamera.h b/interface/src/FancyCamera.h index 3552dc6ca8..d7cf39dd8c 100644 --- a/interface/src/FancyCamera.h +++ b/interface/src/FancyCamera.h @@ -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 mode 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 Camera.cameraEntity property. + * @function Camera.getCameraEntity + * @returns {Uuid} The ID of the entity that the camera is set to follow when in entity mode; null 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 Camera.cameraEntity property. + * @function Camera.setCameraEntity + * @param {Uuid} entityID The entity that the camera should follow when it's in entity mode. + * @example + * Camera.setModeString("entity"); + * var entity = Entities.findClosestEntity(MyAvatar.position, 100.0); + * Camera.setCameraEntity(entity); + */ void setCameraEntity(QUuid entityID); private: diff --git a/libraries/shared/src/shared/Camera.h b/libraries/shared/src/shared/Camera.h index 3ad08bd719..ae096256fc 100644 --- a/libraries/shared/src/shared/Camera.h +++ b/libraries/shared/src/shared/Camera.h @@ -37,12 +37,70 @@ class Camera : public QObject { Q_OBJECT /**jsdoc + * The Camera API provides access to the "camera" that defines your view in desktop and HMD modes. + * + *

+ * + *

Modes:
+ * + *

Camera modes affect the position of the camera and the controls for camera movement. The camera can be in one of the + * following modes:

+ * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
ModeStringDescription
First Person"first person"The camera is positioned such that you have the same view as your avatar. The camera moves and rotates with + * your avatar.
Third Person"third person"The camera is positioned such that you have a view from just behind your avatar. The camera moves and rotates + * with your avatar.
Mirror"mirror"The camera is positioned such that you are looking directly at your avatar. The camera moves and rotates with + * your avatar.
Independent"independent"The camera's position and orientation don't change with your avatar movement. Instead, they can be set via + * scripting.
Entity"entity"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. + *
+ * + *

The camera mode can be changed using Camera.mode and {@link Camera.setModeString}, and Interface's "View" + * menu.

+ * * @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 entity mode. + * @property orientation {Quat} The orientation of the camera. You can set this value only when the camera is in entity + * mode. + * @property mode {String} The camera mode. + * @property frustum {Frustum} 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 +127,116 @@ public: QVariantMap getViewFrustum(); public slots: + /**jsdoc + * Get the current camera mode. You can also get the mode using the Camera.mode property. + * @function Camera.getModeString + * @return {String} The current camera mode. + */ QString getModeString() const; + + /**jsdoc + * Set the camera mode. You can also set the mode using the Camera.mode property. + * @function Camera.setModeString + * @param {String} 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 Camera.position property. + * @function Camera.getPosition + * @return {Vec3} The current camera position. + */ glm::vec3 getPosition() const { return _position; } + + /**jsdoc + * Set the camera position. You can also set the position using the Camera.position 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 Camera.orientation property. + * @function Camera.getOrientation + * @return {Quat} The current camera orientation. + */ glm::quat getOrientation() const { return _orientation; } + + /**jsdoc + * Set the camera orientation. You can also set the orientation using the Camera.orientation 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 {PickRay} based on the current camera configuration and the specified x, y position on the screen. + * The {PickRay} can be used in functions such as {Entities.findRayIntersection} and {Overlays.findRayIntersection}. * @function Camera.computePickRay - * @param {float} x X-coordinate on screen. - * @param {float} y Y-coordinate on screen. + * @param {Number} x - X-coordinate on screen. + * @param {Number} y - Y-coordinate on screen. * @return {PickRay} The computed {PickRay}. + * @example + * 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 position. Only works while in independent. - * camera mode. + * Rotate the camera to look at the specified position. 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 + * 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 position. - * Only works while in `independent` camera mode. + * Set the camera to continue looking at the specified position 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 Camera.keepLookingAt. * @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} + * @example + * function onCameraModeUpdated(newMode) { + * print("The camera mode has changed to " + newMode); + * } + * + * Camera.modeUpdated.connect(onCameraModeUpdated); */ void modeUpdated(const QString& newMode); diff --git a/tools/jsdoc/plugins/hifi.js b/tools/jsdoc/plugins/hifi.js index c15f01efe9..9818f70f6a 100644 --- a/tools/jsdoc/plugins/hifi.js +++ b/tools/jsdoc/plugins/hifi.js @@ -24,6 +24,7 @@ exports.handlers = { '../../libraries/entities/src', '../../libraries/networking/src', '../../libraries/shared/src', + '../../libraries/shared/src/shared', '../../libraries/script-engine/src', ]; var exts = ['.h', '.cpp'];