JDK-8122785 : Document importance of TriangleMesh order of elements
  • Type: Bug
  • Component: javafx
  • Sub-Component: graphics
  • Affected Version: 8
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2013-11-14
  • Updated: 2015-06-17
  • Resolved: 2013-12-06
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 8
8Fixed
Related Reports
Blocks :  
Description
The order of definition of points in a TriangleMesh (clockwise or counter-clockwise) seems to be important and the TriangleMesh Javadoc could be updated to explain the importance.  

I believe this is to do with the notion of front and back sides to a triangle.

For instance, when used in the statement, mesh.getFaces().setAll(faces), the faces array:

        int[] faces = {
            2, 2, 1, 1, 0, 0,
            2, 2, 3, 3, 1, 1
        };

is not the same as the array:

        int[] faces = {
             2, 2, 0, 0, 1, 1,
             2, 2, 1, 1, 3, 3
        };

Even though the arrays seem to be defining the same triangles.

I believe this is because: The direction in which the face is defined is important. The first face array sample defines points 2, 1, 0 (i.e. the triangle is defined in a counter-clockwise order). The second face array sample defines points 2, 0, 1 (clockwise). In an initial untransformed orientation, a face which is defined in a clockwise manner faces away from the viewer. A face which is defined in a counter-clockwise manner faces toward the viewer.

See related StackOverflow question:
  http://stackoverflow.com/questions/19960368/how-to-make-sense-of-javafx-triangle-mesh

Comments
http://cr.openjdk.java.net/~ckyang/RT-34292/webrev.00/
06-12-2013

It is also good to clean up the following javadoc issue in the TriangleMesh class mentioned by Jim: Speaking of which, I was trying to understand TrangleMesh and found odd language in getFaces() where it says that "p0, p1, p2 are indices into points ObservableFloatArray". First, "points" is not highlighted in any way and so it looks like just a descriptive word (unlike "texCoords" in the same statement which is highlighted as a code word)" so for a while I thought "they just gave the name of the type of something, but not the name of the attribute" until I realized that the word "points" was supposed to mean "the thing you access with getPoints()". And second I'm not sure why the (long-winded named) type is mentioned there at all (which was part of why it took me so long to figure out what that sentence was saying) - would it not be enough to say "xxx are indices into the array of {points}" or "into the array of {texCoords}" and be more readable that way? Who cares if those arrays are Observable, and the actual Observable returned from those methods is just a wrapper to facilitate access and tracking through the API, but you are really referring to the data in the underlying internal data structure, not the actual specific way it is accessible via the APIs, right?
19-11-2013