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 8708398..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,61 +1,97 @@
 /*
- * Sixth 3D engine. Copyright ©2012-2018, Svjatoslav Agejenko, svjatoslav@svjatoslav.eu
- *
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of version 3 of the GNU Lesser General Public License
- * or later as published by the Free Software Foundation.
- *
+ * Sixth 3D engine. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
  */
-
-
 package eu.svjatoslav.sixth.e3d.gui;
 
 import eu.svjatoslav.sixth.e3d.geometry.Point3D;
-import eu.svjatoslav.sixth.e3d.math.GeometryCoordinate;
-import eu.svjatoslav.sixth.e3d.math.TransformPipe;
+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;
-    public GeometryCoordinate center = new GeometryCoordinate();
-    public GeometryCoordinate right;
-    public GeometryCoordinate down;
+
+    /**
+     * 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() {
 
     }
 
-    public void analyze(final TransformPipe transformPipe,
+    public void analyze(final TransformsStack transformPipe,
                         final RenderingContext renderingContext) {
 
-        center.transform(transformPipe, renderingContext);
+        center.calculateLocationRelativeToViewer(transformPipe, renderingContext);
 
-        if (right != null) {
-            right.transform(transformPipe, renderingContext);
-            down.transform(transformPipe, renderingContext);
+        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 GeometryCoordinate(new Point3D(10, 0, 0));
-        down = new GeometryCoordinate(new Point3D(0, 10, 0));
+        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();
     }