diff --git a/libraries/shared/src/DebugDraw.h b/libraries/shared/src/DebugDraw.h index 785e549c03..9e3140ca9b 100644 --- a/libraries/shared/src/DebugDraw.h +++ b/libraries/shared/src/DebugDraw.h @@ -22,8 +22,9 @@ #include /**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 DebugDraw 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 0.0 – + * 1.0, with x = red, y = green, z = blue, and w = alpha. + * @example Draw a red ray from your initial avatar position to 10m in front of it. + * 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. + *

Note: 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 0.0 – + * 1.0, with x = red, y = green, z = blue, and w = 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 Draw a red "V" in front of your initial avatar position. + * 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>& 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 name + * 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 Briefly draw a debug marker in front of your avatar, in world coordinates. + * 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 name 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 Briefly draw a debug marker in front of your avatar, in avatar coordinates. + * 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);