From 2d7cc275ccea2e11deeaf02f63c7984a6c09bf4f Mon Sep 17 00:00:00 2001 From: Rami Santina Date: Wed, 30 Mar 2011 13:25:54 +0300 Subject: Added inclass comments to OutlineShape --- src/com/jogamp/graph/curve/OutlineShape.java | 159 ++++++++++++++++++++------ src/com/jogamp/graph/geom/Vertex.java | 2 - src/com/jogamp/graph/geom/opengl/SVertex.java | 7 +- 3 files changed, 124 insertions(+), 44 deletions(-) (limited to 'src/com/jogamp/graph') diff --git a/src/com/jogamp/graph/curve/OutlineShape.java b/src/com/jogamp/graph/curve/OutlineShape.java index 9373808f1..c385b83f5 100755 --- a/src/com/jogamp/graph/curve/OutlineShape.java +++ b/src/com/jogamp/graph/curve/OutlineShape.java @@ -44,33 +44,85 @@ import com.jogamp.graph.curve.tess.CDTriangulator2D; * closed region defined by the outlines. * * One or more OutlineShape Object can be associated to a region - * this is left high-level representation of the Objects. For - * possible Optimizations. + * this is left as a high-level representation of the Objects. For + * optimizations, flexibility requirements for future features. * + *

+ * Example to creating an Outline Shape: + * 
+  	addVertex(...)
+  	addVertex(...)
+  	addVertex(...)
+  	addEnptyOutline()
+  	addVertex(...)
+  	addVertex(...)
+  	addVertex(...)
+ *
+ * + * The above will create two outlines each with three vertices. By adding these two outlines to + * the OutlineShape, we are stating that the combination of the two outlines represent the shape. + *
+ * + * To specify that the shape is curved at a region, the on-curve flag should be set to false + * for the vertex that is in the middle of the curved region (if the curved region is defined by 3 + * vertices (quadratic curve). + *
+ * In case the curved region is defined by 4 or more vertices the middle vertices should both have + * the on-curve flag set to false. + * + *
Example:
+ * 
+  	addVertex(0,0, true);
+  	addVertex(0,1, false);
+  	addVertex(1,1, false);
+  	addVertex(1,0, true);
+ *
+ * + * The above snippet defines a cubic nurbs curve where (0,1 and 1,1) + * do not belong to the final rendered shape. + * + * Implementation Notes:
+ * + * + * @see Outline * @see Region */ public class OutlineShape { + public static final int QUADRATIC_NURBS = 10; - private final Vertex.Factory pointFactory; + private final Vertex.Factory vertexFactory; + + /** The list of outlines that are part of this + * outline shape. + */ private ArrayList> outlines = new ArrayList>(3); - + /** Create a new Outline based Shape */ public OutlineShape(Vertex.Factory factory) { - pointFactory = factory; + vertexFactory = factory; outlines.add(new Outline()); } - - public final Vertex.Factory pointFactory() { return pointFactory; } - + + /** Returns the associated vertex factory of this outline shape + * @return Vertex.Factory object + */ + public final Vertex.Factory vertexFactory() { return vertexFactory; } + /** Add a new empty outline * to the shape, this new outline will * be placed at the end of the outline list. + * + * After a call to this function all new vertices added + * will belong to the new outline */ public void addEmptyOutline(){ outlines.add(new Outline()); } - + /** Adds an outline to the OutlineShape object * if last outline of the shape is empty, it will replace * that last Outline with the new one. If outline is empty, @@ -86,27 +138,52 @@ public class OutlineShape { } outlines.add(outline); } - + /** Adds a vertex to the last open outline in the - * shape - * @param point + * shape. + * @param v the vertex to be added to the OutlineShape */ - public final void addVertex(Vertex point){ - getLastOutline().addVertex(point); + public final void addVertex(Vertex v){ + getLastOutline().addVertex(v); } - + + /** Add a 2D vertex to the last outline by defining the coordniate attribute + * of the vertex. The 2D vertex will be represented as Z=0. + * + * @param x the x coordinate + * @param y the y coordniate + * @param onCurve flag if this vertex is on the final curve or defines a curved region + * of the shape around this vertex. + */ public final void addVertex(float x, float y, boolean onCurve) { - getLastOutline().addVertex(pointFactory, x, y, onCurve); + getLastOutline().addVertex(vertexFactory, x, y, onCurve); } - + + /** Add a 3D vertex to the last outline by defining the coordniate attribute + * of the vertex. + * @param x the x coordinate + * @param y the y coordniate + * @param z the z coordniate + * @param onCurve flag if this vertex is on the final curve or defines a curved region + * of the shape around this vertex. + */ public final void addVertex(float x, float y, float z, boolean onCurve) { - getLastOutline().addVertex(pointFactory, x, y, z, onCurve); + getLastOutline().addVertex(vertexFactory, x, y, z, onCurve); } - + + /** Add a vertex to the last outline by passing a float array and specifying the offset and length in which. + * the attributes of the vertex are located. The attributes should be continuous (stride = 0). + * Attributes which value are not set (when length less than 3) are set implicitly to zero. + * @param coordsBuffer the coordinate array where the vertex attributes are to be picked from + * @param offset the offset in the buffer to the x coordinate + * @param length the number of attributes to pick from the buffer (maximum 3) + * @param onCurve flag if this vertex is on the final curve or defines a curved region + * of the shape around this vertex. + */ public final void addVertex(float[] coordsBuffer, int offset, int length, boolean onCurve) { - getLastOutline().addVertex(pointFactory, coordsBuffer, offset, length, onCurve); + getLastOutline().addVertex(vertexFactory, coordsBuffer, offset, length, onCurve); } - + /** Closes the last outline in the shape * if last vertex is not equal to first vertex. * A new temp vertex is added at the end which @@ -115,7 +192,7 @@ public class OutlineShape { public void closeLastOutline(){ getLastOutline().setClosed(true); } - + /** Get the last added outline to the list * of outlines that define the shape * @return the last outline @@ -125,7 +202,7 @@ public class OutlineShape { } /** Make sure that the outlines represent * the specified destinationType, if not - * transform outlines to destinationType. + * transform outlines to destination type. * @param destinationType The curve type needed */ public void transformOutlines(int destinationType){ @@ -133,7 +210,7 @@ public class OutlineShape { transformOutlinesQuadratic(); } } - + private void transformOutlinesQuadratic(){ ArrayList> newOutlines = new ArrayList>(3); @@ -150,9 +227,9 @@ public class OutlineShape { Vertex nextVertex = vertices.get((i+1)%size); if(!(currentVertex.isOnCurve()) && !(nextVertex.isOnCurve())) { newOutline.addVertex(currentVertex); - + float[] newCoords = VectorUtil.mid(currentVertex.getCoord(), nextVertex.getCoord()); - newOutline.addVertex(pointFactory, newCoords, 0, 3, true); + newOutline.addVertex(vertexFactory, newCoords, 0, 3, true); } else { newOutline.addVertex(currentVertex); @@ -162,7 +239,7 @@ public class OutlineShape { } outlines = newOutlines; } - + private void generateVertexIds(){ int maxVertexId = 0; for(Outline outline:outlines){ @@ -173,7 +250,7 @@ public class OutlineShape { } } } - + /** @return the list of vertices associated with the * {@code Outline} list of this object */ @@ -184,10 +261,20 @@ public class OutlineShape { } return vertices; } - - /** Triangluate the graph object - * @param sharpness sharpness of the curved regions default = 0.5 + /** Triangulate the outline shape generating a list of triangles + * @return an arraylist of triangles representing the filled region + * which is produced by the combination of the outlines + */ + public ArrayList> triangulate(){ + return triangulate(0.5f); + } + + /**Triangulate the outline shape generating a list of triangles + * @param sharpness defines the curvature strength around the off-curve vertices. + * defaults to 0.5f + * @return an arraylist of triangles representing the filled region + * which is produced by the combination of the outlines */ public ArrayList> triangulate(float sharpness){ if(outlines.size() == 0){ @@ -195,20 +282,20 @@ public class OutlineShape { } sortOutlines(); generateVertexIds(); - + CDTriangulator2D triangulator2d = new CDTriangulator2D(sharpness); - + for(int index = 0; index< outlines.size();index++){ Outline outline = outlines.get(index); triangulator2d.addCurve(outline); } - + ArrayList> triangles = triangulator2d.generateTriangulation(); triangulator2d.reset(); - + return triangles; } - + /** Sort the outlines from large * to small depending on the AABox */ diff --git a/src/com/jogamp/graph/geom/Vertex.java b/src/com/jogamp/graph/geom/Vertex.java index 9d19c89f6..0e4e5e8df 100644 --- a/src/com/jogamp/graph/geom/Vertex.java +++ b/src/com/jogamp/graph/geom/Vertex.java @@ -40,8 +40,6 @@ public interface Vertex extends Comparable, Cloneable { T create(float x, float y, float z); T create(float[] coordsBuffer, int offset, int length); - - // T[] create(T ... v); } void setCoord(float x, float y); diff --git a/src/com/jogamp/graph/geom/opengl/SVertex.java b/src/com/jogamp/graph/geom/opengl/SVertex.java index 076ac7456..37ce71a40 100644 --- a/src/com/jogamp/graph/geom/opengl/SVertex.java +++ b/src/com/jogamp/graph/geom/opengl/SVertex.java @@ -61,11 +61,6 @@ public class SVertex implements Vertex { public SVertex create(float[] coordsBuffer, int offset, int length) { return new SVertex(coordsBuffer, offset, length); } - - /* @Override - public Vertex[] create(Vertex ... v) { - return v; - } */ } public SVertex() { @@ -98,7 +93,7 @@ public class SVertex implements Vertex { throw new IndexOutOfBoundsException("coordsBuffer too small: "+coordsBuffer.length+" - "+offset+" < "+length); } if(length > 3) { - throw new IndexOutOfBoundsException("length too bug: "+length+" > "+3); + throw new IndexOutOfBoundsException("length too big: "+length+" > "+3); } int i=0; while(i