sigonasr2
/
jmonkeyengine
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

improve javadoc in Triangle: "center" -> "centroid", "point" -> "vertex"

Browse Source
master
Stephen Gold 5 years ago
parent 84c88709b5
commit f6c467b495
1 changed files with 64 additions and 58 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 122
      jme3-core/src/main/java/com/jme3/math/Triangle.java

122
jme3-core/src/main/java/com/jme3/math/Triangle.java
Unescape View File

@ -37,9 +37,9 @@ import com.jme3.export.Savable;
import java.io.IOException;
/**
* <code>Triangle</code> defines an object for containing triangle information.
* The triangle is defined by a collection of three {@link Vector3f}
* objects.
* <code>Triangle</code> 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 <Code>Triangle</code> 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 <Code>Triangle</code> 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
}
/**
* <code>get</code> 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
}
/**
* <code>set</code> 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
}
/**
* <code>set</code> 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
}
/**
* <code>set1</code> 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
}
/**
* <code>set2</code> 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
}
/**
* <code>set3</code> 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
}
/**
* <code>set</code> 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();

Write Preview
Loading…
Cancel
Save