Exposed DebugDraw interface to Java Script

libraries/script-engine/src/Quat.h

@@ -19,6 +19,16 @@
 #include <QObject>
 #include <QString>
 
+/**jsdoc
+ * A Quaternion
+ *
+ * @typedef Quat
+ * @property {float} x imaginary component i.
+ * @property {float} y imaginary component j.
+ * @property {float} z imaginary component k.
+ * @property {float} w real component.
+ */
+
 /// Scriptable interface a Quaternion helper class object. Used exclusively in the JavaScript API
 class Quat : public QObject {
     Q_OBJECT

libraries/script-engine/src/ScriptEngine.cpp

@@ -34,6 +34,7 @@
 #include <AudioConstants.h>
 #include <AudioEffectOptions.h>
 #include <AvatarData.h>
+#include <DebugDraw.h>
 #include <EntityScriptingInterface.h>
 #include <MessagesClient.h>
 #include <NetworkAccessManager.h>
@@ -630,6 +631,8 @@ void ScriptEngine::init() {
     registerGlobalObject("Tablet", DependencyManager::get<TabletScriptingInterface>().data());
     registerGlobalObject("Assets", &_assetScriptingInterface);
     registerGlobalObject("Resources", DependencyManager::get<ResourceScriptingInterface>().data());
+
+    registerGlobalObject("DebugDraw", &DebugDraw::getInstance());
 }
 
 void ScriptEngine::registerValue(const QString& valueName, QScriptValue value) {

libraries/script-engine/src/Vec3.h

@@ -37,6 +37,15 @@
  * @property {float} z Z-coordinate of the vector.
  */
 
+/**jsdoc
+ * A 4-dimensional vector.
+ *
+ * @typedef 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.
+ * @property {float} w W-coordinate of the vector.
+ */
 
 /// Scriptable interface a Vec3ernion helper class object. Used exclusively in the JavaScript API
 class Vec3 : public QObject {

libraries/shared/src/DebugDraw.cpp

@@ -28,19 +28,19 @@ void DebugDraw::drawRay(const glm::vec3& start, const glm::vec3& end, const glm:
     _rays.push_back(Ray(start, end, color));
 }
 
-void DebugDraw::addMarker(const std::string& key, const glm::quat& rotation, const glm::vec3& position, const glm::vec4& color) {
+void DebugDraw::addMarker(const QString& key, const glm::quat& rotation, const glm::vec3& position, const glm::vec4& color) {
     _markers[key] = MarkerInfo(rotation, position, color);
 }
 
-void DebugDraw::removeMarker(const std::string& key) {
+void DebugDraw::removeMarker(const QString& key) {
     _markers.erase(key);
 }
 
-void DebugDraw::addMyAvatarMarker(const std::string& key, const glm::quat& rotation, const glm::vec3& position, const glm::vec4& color) {
+void DebugDraw::addMyAvatarMarker(const QString& key, const glm::quat& rotation, const glm::vec3& position, const glm::vec4& color) {
     _myAvatarMarkers[key] = MarkerInfo(rotation, position, color);
 }
 
-void DebugDraw::removeMyAvatarMarker(const std::string& key) {
+void DebugDraw::removeMyAvatarMarker(const QString& key) {
     _myAvatarMarkers.erase(key);
 }
 

libraries/shared/src/DebugDraw.h

@@ -17,26 +17,69 @@
 #include <glm/glm.hpp>
 #include <glm/gtc/quaternion.hpp>
 
-class DebugDraw {
+#include <QObject>
+#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.
+ * @namespace DebugDraw
+ */
+class DebugDraw : public QObject {
+    Q_OBJECT
 public:
     static DebugDraw& getInstance();
 
     DebugDraw();
     ~DebugDraw();
 
-    // world space line, drawn only once
-    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.
+     */
+    Q_INVOKABLE void drawRay(const glm::vec3& start, const glm::vec3& end, const glm::vec4& color);
 
-    // world space maker, marker drawn every frame until it is removed.
-    void addMarker(const std::string& key, const glm::quat& rotation, const glm::vec3& position, const glm::vec4& color);
-    void removeMarker(const std::string& key);
+    /**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.
+     * @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.
+     */
+    Q_INVOKABLE void addMarker(const QString& key, const glm::quat& rotation, const glm::vec3& position, const glm::vec4& color);
 
-    // myAvatar relative marker, maker is drawn every frame until it is removed.
-    void addMyAvatarMarker(const std::string& key, const glm::quat& rotation, const glm::vec3& position, const glm::vec4& color);
-    void removeMyAvatarMarker(const std::string& key);
+    /**jsdoc
+     * Removes debug marker from the world.  Once a marker is removed, it will no longer be visible.
+     * @function DebugDraw.removeMarker
+     * @param {string} key - name of 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.
+     * @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 {Vec4} color - color of the marker.
+     */
+    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
+     * @function DebugDraw.removeMyAvatarMarker
+     * @param {string} key - name of marker to remove.
+     */
+    Q_INVOKABLE void removeMyAvatarMarker(const QString& key);
 
     using MarkerInfo = std::tuple<glm::quat, glm::vec3, glm::vec4>;
-    using MarkerMap = std::unordered_map<std::string, MarkerInfo>;
+    using MarkerMap = std::map<QString, MarkerInfo>;
     using Ray = std::tuple<glm::vec3, glm::vec3, glm::vec4>;
     using Rays = std::vector<Ray>;
 

tools/jsdoc/plugins/hifi.js

@@ -21,6 +21,7 @@ exports.handlers = {
             '../../libraries/networking/src',
             '../../libraries/animation/src',
             '../../libraries/entities/src',
+            '../../libraries/shared/src'
         ];
         var exts = ['.h', '.cpp'];