Mirrors/overte-Armored-Dragon
3
0
Fork 0
mirror of https://github.com/Armored-Dragon/overte.git synced 2025-03-11 16:13:16 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

Update JSDoc for Camera API

Browse source
This commit is contained in:
David Rowe 2017-11-12 11:04:35 +13:00
parent f5e155bf94
commit 39ccd7d656
3 changed files with 165 additions and 20 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
* Camera.setModeString("entity");
* var entity = Entities.findClosestEntity(MyAvatar.position, 100.0);
* Camera.setCameraEntity(entity);
*/
void setCameraEntity(QUuid entityID);
private:

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

@ -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.
*
* <p />
*
* <h5>Modes:</h5>
*
* <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>
*
* <p>The camera mode can be changed using <code>Camera.mode</code> and {@link Camera.setModeString}, and Interface's "View"
* menu.</p>
*
* @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 <code>Camera.mode</code> 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 <code>Camera.mode</code> 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 <code>Camera.position</code> 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 <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
* @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 <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 {PickRay} based on the current camera configuration and the specified <code>x, y</code> 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 <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
* 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}
* @example
* function onCameraModeUpdated(newMode) {
* print("The camera mode has changed to " + newMode);
* }
*
* Camera.modeUpdated.connect(onCameraModeUpdated);
*/
void modeUpdated(const QString& newMode);

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

@ -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'];