Mirrors/overte-HifiExperiments
3
0
Fork 0
mirror of https://github.com/HifiExperiments/overte.git synced 2025-04-07 10:02:24 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge pull request #16011 from ctrlaltdavid/DOC-60

Browse source 
Case 22106: DebugDraw JSDoc
This commit is contained in:
Shannon Romano 2019-08-06 10:47:43 -07:00 committed by GitHub
commit f02b76fed0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 78 additions and 27 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

105
libraries/shared/src/DebugDraw.h
View file

@ -22,8 +22,9 @@
#include <QString>
/**jsdoc
* Helper functions to render ephemeral debug markers and lines.
* DebugDraw markers and lines are only visible locally, they are not visible by other users.
* The <code>DebugDraw</code> API renders debug markers and lines. These markers are only visible locally; they are not visible
* to other users.
*
* @namespace DebugDraw
*
* @hifi-interface
@ -41,57 +42,107 @@ public:
~DebugDraw();
/**jsdoc
* Draws a line in world space, but it will only be visible for a single frame.
* Draws a line in world space, visible for a single frame. To make the line visually persist, you need to repeatedly draw
* it.
* @function DebugDraw.drawRay
* @param {Vec3} start - start position of line in world space.
* @param {Vec3} end - end position of line in world space.
* @param {Vec4} color - color of line, each component should be in the zero to one range. x = red, y = blue, z = green, w = alpha.
* @param {Vec3} start - The start position of the line, in world coordinates.
* @param {Vec3} end - The end position of the line, in world coordinates.
* @param {Vec4} color - The color of the line. Each component should be in the range <code>0.0</code> &ndash;
* <code>1.0</code>, with <code>x</code> = red, <code>y</code> = green, <code>z</code> = blue, and <code>w</code> = alpha.
* @example <caption>Draw a red ray from your initial avatar position to 10m in front of it.</caption>
* var start = MyAvatar.position;
* var end = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -10 }));
* var color = { x: 1.0, y: 0.0, z: 0.0, w: 1.0 };
*
* Script.update.connect(function () {
* DebugDraw.drawRay(start, end, color);
* });
*/
Q_INVOKABLE void drawRay(const glm::vec3& start, const glm::vec3& end, const glm::vec4& color);
/**jsdoc
* Draws a line in world space, but it will only be visible for a single frame.
* @function DebugDraw.drawRay
* @param {Vec3} start - start position of line in world space.
* @param {Vec3} end - end position of line in world space.
* @param {Vec4} color - color of line, each component should be in the zero to one range. x = red, y = blue, z = green, w = alpha.
*/
* Draws lines in world space, visible for a single frame. To make the lines visually persist, you need to repeatedly draw
* them.
* <p><strong>Note:</strong> Currently doesn't work.
* @function DebugDraw.drawRays
* @param {Vec3Pair[]} lines - The start and end points of the lines to draw.
* @param {Vec4} color - The color of the lines. Each component should be in the range <code>0.0</code> &ndash;
* <code>1.0</code>, with <code>x</code> = red, <code>y</code> = green, <code>z</code> = blue, and <code>w</code> = alpha.
* @param {Vec3} [translation=0,0,0] - A translation applied to each line.
* @param {Quat} [rotation=Quat.IDENTITY] - A rotation applied to each line.
* @example <caption>Draw a red "V" in front of your initial avatar position.</caption>
* var lines = [
* [{ x: -1, y: 0.5, z: 0 }, { x: 0, y: 0, z: 0 }],
* [{ x: 0, y: 0, z: 0 }, { x: 1, y: 0.5, z: 0 }]
* ];
* var color = { x: 1, y: 0, z: 0, w: 1 };
* var translation = Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0.75, z: -5 }));
* var rotation = MyAvatar.orientation;
*
* Script.update.connect(function () {
* DebugDraw.drawRays(lines, color, translation, rotation);
* });
*/
Q_INVOKABLE void drawRays(const std::vector<std::pair<glm::vec3, glm::vec3>>& lines, const glm::vec4& color,
const glm::vec3& translation = glm::vec3(0.0f, 0.0f, 0.0f), const glm::quat& rotation = glm::quat(1.0f, 0.0f, 0.0f, 0.0f));
/**jsdoc
* Adds a debug marker to the world. This marker will be drawn every frame until it is removed with DebugDraw.removeMarker.
* This can be called repeatedly to change the position of the marker.
* Adds or updates a debug marker in world coordinates. This marker is drawn every frame until it is removed using
* {@link DebugDraw.removeMarker|removeMarker}. If a world coordinates debug marker of the specified <code>name</code>
* already exists, its parameters are updated.
* @function DebugDraw.addMarker
* @param {string} key - name to uniquely identify this marker, later used for DebugDraw.removeMarker.
* @param {Quat} rotation - start position of line in world space.
* @param {Vec3} position - position of the marker in world space.
* @param {Vec4} color - color of the marker.
* @param {string} key - A name that uniquely identifies the marker.
* @param {Quat} rotation - The orientation of the marker in world coordinates.
* @param {Vec3} position - The position of the market in world coordinates.
* @param {Vec4} color - The color of the marker.
* @example <caption>Briefly draw a debug marker in front of your avatar, in world coordinates.</caption>
* var MARKER_NAME = "my marker";
* DebugDraw.addMarker(
* MARKER_NAME,
* Quat.ZERO,
* Vec3.sum(MyAvatar.position, Vec3.multiplyQbyV(MyAvatar.orientation, { x: 0, y: 0, z: -5})),
* { red: 255, green: 0, blue: 0 }
* );
* Script.setTimeout(function () {
* DebugDraw.removeMarker(MARKER_NAME);
* }, 5000);
*/
Q_INVOKABLE void addMarker(const QString& key, const glm::quat& rotation, const glm::vec3& position, const glm::vec4& color);
/**jsdoc
* Removes debug marker from the world. Once a marker is removed, it will no longer be visible.
* Removes a debug marker that was added in world coordinates.
* @function DebugDraw.removeMarker
* @param {string} key - name of marker to remove.
* @param {string} key - The name of the world coordinates debug marker to remove.
*/
Q_INVOKABLE void removeMarker(const QString& key);
/**jsdoc
* Adds a debug marker to the world, this marker will be drawn every frame until it is removed with DebugDraw.removeMyAvatarMarker.
* This can be called repeatedly to change the position of the marker.
* Adds or updates a debug marker to the world in avatar coordinates. This marker is drawn every frame until it is removed
* using {@link DebugDraw.removeMyAvatarMarker|removeMyAvatarMarker}. If an avatar coordinates debug marker of the
* specified <code>name</code> already exists, its parameters are updated. The debug marker moves with your avatar.
* @function DebugDraw.addMyAvatarMarker
* @param {string} key - name to uniquely identify this marker, later used for DebugDraw.removeMyAvatarMarker.
* @param {Quat} rotation - start position of line in avatar space.
* @param {Vec3} position - position of the marker in avatar space.
* @param {string} key - A name that uniquely identifies the marker.
* @param {Quat} rotation - The orientation of the marker in avatar coordinates.
* @param {Vec3} position - The position of the market in avatar coordinates.
* @param {Vec4} color - color of the marker.
* @example <caption>Briefly draw a debug marker in front of your avatar, in avatar coordinates.</caption>
* var MARKER_NAME = "My avatar marker";
* DebugDraw.addMyAvatarMarker(
* MARKER_NAME,
* Quat.ZERO,
* { x: 0, y: 0, z: -5 },
* { red: 255, green: 0, blue: 0 }
* );
* Script.setTimeout(function () {
* DebugDraw.removeMyAvatarMarker(MARKER_NAME);
* }, 5000);
*/
Q_INVOKABLE void addMyAvatarMarker(const QString& key, const glm::quat& rotation, const glm::vec3& position, const glm::vec4& color);
/**jsdoc
* Removes debug marker from the world. Once a marker is removed, it will no longer be visible
* Removes a debug marker that was added in avatar coordinates.
* @function DebugDraw.removeMyAvatarMarker
* @param {string} key - name of marker to remove.
* @param {string} key - The name of the avatar coordinates debug marker to remove.
*/
Q_INVOKABLE void removeMyAvatarMarker(const QString& key);