From f6c467b495f8556d6d0b204776d6ad16b418d4d7 Mon Sep 17 00:00:00 2001 From: Stephen Gold Date: Mon, 20 Apr 2020 16:44:44 -0700 Subject: [PATCH] improve javadoc in Triangle: "center" -> "centroid", "point" -> "vertex" --- .../src/main/java/com/jme3/math/Triangle.java | 122 +++++++++--------- 1 file changed, 64 insertions(+), 58 deletions(-) diff --git a/jme3-core/src/main/java/com/jme3/math/Triangle.java b/jme3-core/src/main/java/com/jme3/math/Triangle.java index e87390c71..8bb1fffc6 100644 --- a/jme3-core/src/main/java/com/jme3/math/Triangle.java +++ b/jme3-core/src/main/java/com/jme3/math/Triangle.java @@ -37,9 +37,9 @@ import com.jme3.export.Savable; import java.io.IOException; /** - * Triangle defines an object for containing triangle information. - * The triangle is defined by a collection of three {@link Vector3f} - * objects. + * Triangle defines a triangle in terms of its vertex locations, + * with auxiliary storage for its centroid, normal vector, projection, and + * index. * * @author Mark Powell * @author Joshua Slack @@ -62,14 +62,13 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja } /** - * Constructor instantiates a new Triangle object with the - * supplied vectors as the points. It is recommended that the vertices - * be supplied in a counter clockwise winding to support normals for a - * right handed coordinate system. + * Instantiate a Triangle with the specified vertex locations. + * Vertices should be listed in the desired winding order, typically + * counter-clockwise. * - * @param p1 the first point of the triangle. - * @param p2 the second point of the triangle. - * @param p3 the third point of the triangle. + * @param p1 the location of the first vertex (not null, unaffected) + * @param p2 the location of the 2nd vertex (not null, unaffected) + * @param p3 the location of the 3rd vertex (not null, unaffected) */ public Triangle(Vector3f p1, Vector3f p2, Vector3f p3) { pointa.set(p1); @@ -78,11 +77,10 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja } /** - * get retrieves a point on the triangle denoted by the index - * supplied. + * Access the location of the indexed vertex. * - * @param i the index of the point (0, 1, or 2) - * @return a pre-existing location vector + * @param i the index of the vertex to access (0, 1, or 2) + * @return a pre-existing location vector, or null if the index is invalid */ public Vector3f get(int i) { switch (i) { @@ -98,9 +96,9 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja } /** - * Access the location of the 1st point (A). + * Access the location of the first vertex. * - * @return the pre-existing vector (not null) + * @return the pre-existing location vector (not null) */ @Override public Vector3f get1() { @@ -108,9 +106,9 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja } /** - * Access the location of the 2nd point (B). + * Access the location of the 2nd vertex. * - * @return the pre-existing vector (not null) + * @return the pre-existing location vector (not null) */ @Override public Vector3f get2() { @@ -118,9 +116,9 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja } /** - * Access the location of the 3rd point (C). + * Access the location of the 3rd vertex. * - * @return the pre-existing vector (not null) + * @return the pre-existing location vector (not null) */ @Override public Vector3f get3() { @@ -128,11 +126,11 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja } /** - * set sets one of the triangle's points to that specified as a - * parameter. + * Alter the location of the indexed vertex and delete the stored centroid + * and normal. * - * @param i the index to place the point (0, 1, or 2) - * @param point the desired location of the point (not null, unaffected) + * @param i the index of the vertex to alter (0, 1, or 2) + * @param point the desired location (not null, unaffected) */ public void set(int i, Vector3f point) { center = null; @@ -152,12 +150,13 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja } /** - * set alters the location of one of the triangle's points. + * Alter the location of the indexed vertex and delete the stored centroid + * and normal. * - * @param i the index to place the point (0, 1, or 2) - * @param x the desired X-component of the point's location - * @param y the desired Y-component of the point's location - * @param z the desired Z-component of the point's location + * @param i the index of the vertex to alter (0, 1, or 2) + * @param x the desired X coordinate + * @param y the desired Y coordinate + * @param z the desired Z coordinate */ public void set(int i, float x, float y, float z) { center = null; @@ -177,7 +176,8 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja } /** - * set1 alters the location of the triangle's 1st point. + * Alter the location of the first vertex and delete the stored centroid and + * normal. * * @param v the desired location (not null, unaffected) */ @@ -189,7 +189,8 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja } /** - * set2 alters the location of the triangle's 2nd point. + * Alter the location of the 2nd vertex and delete the stored centroid and + * normal. * * @param v the desired location (not null, unaffected) */ @@ -201,7 +202,8 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja } /** - * set3 alters the location of the triangle's 3rd point. + * Alter the location of the 3rd vertex and delete the stored centroid and + * normal. * * @param v the desired location (not null, unaffected) */ @@ -213,11 +215,12 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja } /** - * set alters the locations of all 3 points. + * Alter the locations of all 3 vertices and delete the stored centroid and + * normal. * - * @param v1 the desired location of the 1st point (not null, unaffected) - * @param v2 the desired location of the 2nd point (not null, unaffected) - * @param v3 the desired location of the 3rd point (not null, unaffected) + * @param v1 the desired location of the first vertex (not null, unaffected) + * @param v2 the desired location of the 2nd vertex (not null, unaffected) + * @param v3 the desired location of the 3rd vertex (not null, unaffected) */ @Override public void set(Vector3f v1, Vector3f v2, Vector3f v3) { @@ -230,7 +233,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja } /** - * calculateCenter finds the average point of the triangle. + * Recalculate the stored centroid based on the current vertex locations. */ public void calculateCenter() { if (center == null) { @@ -242,8 +245,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja } /** - * calculateNormal generates the normal for this triangle - * + * Recalculate the stored normal based on the current vertex locations. */ public void calculateNormal() { if (normal == null) { @@ -256,9 +258,11 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja } /** - * obtains the center point of this triangle (average of the three triangles) + * Access the stored centroid (the average of the 3 vertex locations) + * calculating it if it is null. * - * @return the center point. + * @return the coordinates of the center (an internal vector subject to + * re-use) */ public Vector3f getCenter() { if (center == null) { @@ -268,19 +272,19 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja } /** - * sets the center point of this triangle (average of the three triangles) + * Alter the stored centroid without affecting the stored normal or any + * vertex locations. * - * @param center the center point. + * @param center the desired value (alias created if not null) */ public void setCenter(Vector3f center) { this.center = center; } /** - * obtains the unit length normal vector of this triangle, if set or - * calculated + * Access the stored normal, updating it if it is null. * - * @return the normal vector + * @return unit normal vector (an internal vector subject to re-use) */ public Vector3f getNormal() { if (normal == null) { @@ -290,45 +294,46 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja } /** - * sets the normal vector of this triangle (to conform, must be unit length) + * Alter the stored normal without affecting the stored centroid or any + * vertex locations. * - * @param normal the normal vector. + * @param normal the desired value (alias created if not null) */ public void setNormal(Vector3f normal) { this.normal = normal; } /** - * obtains the projection of the vertices relative to the line origin. + * Read the projection of the vertices relative to the line origin. * - * @return the projection of the triangle. + * @return the stored projection value */ public float getProjection() { return this.projection; } /** - * sets the projection of the vertices relative to the line origin. + * Alter the projection of the vertices relative to the line origin. * - * @param projection the projection of the triangle. + * @param projection the desired projection value */ public void setProjection(float projection) { this.projection = projection; } /** - * obtains an index that this triangle represents if it is contained in a OBBTree. + * Read the index of this triangle, used to identify it in an OBBTree. * - * @return the index in an OBBtree + * @return the stored index */ public int getIndex() { return index; } /** - * sets an index that this triangle represents if it is contained in a OBBTree. + * Alter the index of this triangle, used to identify it in an OBBTree. * - * @param index the index in an OBBtree + * @param index the desired index */ public void setIndex(int index) { this.index = index; @@ -360,8 +365,8 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja } /** - * De-serialize this triangle from the specified importer, for example - * when loading from a J3O file. + * De-serialize this triangle from the specified importer, for example when + * loading from a J3O file. * * @param e (not null) * @throws IOException from the importer @@ -385,6 +390,7 @@ public class Triangle extends AbstractTriangle implements Savable, Cloneable, ja t.pointa = pointa.clone(); t.pointb = pointb.clone(); t.pointc = pointc.clone(); + // XXX: the center and normal are not cloned! return t; } catch (CloneNotSupportedException e) { throw new AssertionError();