Fixed git clone URL

[sixth-3d.git] / src / main / java / eu / svjatoslav / sixth / e3d / gui / UserRelativityTracker.java

diff --git a/src/main/java/eu/svjatoslav/sixth/e3d/gui/UserRelativityTracker.java b/src/main/java/eu/svjatoslav/sixth/e3d/gui/UserRelativityTracker.java
index 48b1016..d491b0f 100644 (file)
--- a/src/main/java/eu/svjatoslav/sixth/e3d/gui/UserRelativityTracker.java
+++ b/src/main/java/eu/svjatoslav/sixth/e3d/gui/UserRelativityTracker.java
@@ -1,5 +1,5 @@
 /*
- * Sixth 3D engine. Author: Svjatoslav Agejenko. 
+ * Sixth 3D engine. Author: Svjatoslav Agejenko.
  * This project is released under Creative Commons Zero (CC0) license.
  */
 package eu.svjatoslav.sixth.e3d.gui;
@@ -8,11 +8,32 @@ import eu.svjatoslav.sixth.e3d.geometry.Point3D;
 import eu.svjatoslav.sixth.e3d.math.TransformsStack;
 import eu.svjatoslav.sixth.e3d.math.Vertex;
 
+/**
+ * Tracks the position of the user in the 3D space.
+ * <p>
+ * It can be used to determine the angle between the user and the object.
+ * Also, it can be used to determine the distance between the user and the object.
+ */
+
 public class UserRelativityTracker {
 
     private final static int minimalSliceFactor = 5;
+
+    /**
+     * Points to 0, 0, 0 in object own relative space.
+     */
     public Vertex center = new Vertex();
+
+    /**
+     * Points to 10, 0, 0 in object own relative space if orientation tracking is enabled.
+     * It is used to determine the angle between the user and the object.
+     */
     public Vertex right;
+
+    /**
+     * Points to 0, 10, 0 in object own relative space if orientation tracking is enabled.
+     * It is used to determine the angle between the user and the object.
+     */
     public Vertex down;
 
     public UserRelativityTracker() {
@@ -24,32 +45,53 @@ public class UserRelativityTracker {
 
         center.calculateLocationRelativeToViewer(transformPipe, renderingContext);
 
-        if (right != null) {
+        if (right != null) { // If orientation tracking is enabled.
             right.calculateLocationRelativeToViewer(transformPipe, renderingContext);
             down.calculateLocationRelativeToViewer(transformPipe, renderingContext);
         }
     }
 
+    /**
+     * Initializes the orientation tracking.
+     * Orientation tracking is used to determine the angle between the user and the object.
+     * Orientation tracking is disabled by default and it is optional.
+     */
     public void enableOrientationTracking() {
         right = new Vertex(new Point3D(10, 0, 0));
         down = new Vertex(new Point3D(0, 10, 0));
     }
 
+    /**
+     * Calculates the angle between the user and the object in the XY plane.
+     * @return the angle between the user and the object in the XY plane.
+     */
     public double getAngleXY() {
         return center.transformedCoordinate
                 .getAngleXY(down.transformedCoordinate);
     }
 
+    /**
+     * Calculates the angle between the user and the object in the XZ plane.
+     * @return the angle between the user and the object in the XZ plane.
+     */
     public double getAngleXZ() {
         return center.transformedCoordinate
                 .getAngleXZ(right.transformedCoordinate);
     }
 
+    /**
+     * Calculates the angle between the user and the object in the YZ plane.
+     * @return the angle between the user and the object in the YZ plane.
+     */
     public double getAngleYZ() {
         return center.transformedCoordinate
                 .getAngleYZ(down.transformedCoordinate);
     }
 
+    /**
+     * Calculates the distance between the user and the object.
+     * Distance to the user can be used to determine object detail level.
+     */
     public double getDistanceToUser() {
         return center.transformedCoordinate.getVectorLength();
     }