X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Feu%2Fsvjatoslav%2Fsixth%2Fe3d%2Fgui%2FUserRelativityTracker.java;h=d491b0fe55da242210a1884530fdcb20a401fecb;hb=HEAD;hp=ae6d46418f27d35281746b303038a8d422de60dd;hpb=59baa428fb2d9e7f0fe5423f4cea47f2d6245914;p=sixth-3d.git

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 ae6d464..d491b0f 100644
--- 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-2019, 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();
     }