diff options
Diffstat (limited to 'src/jogl/classes/com')
3 files changed, 163 insertions, 56 deletions
diff --git a/src/jogl/classes/com/jogamp/graph/curve/OutlineShape.java b/src/jogl/classes/com/jogamp/graph/curve/OutlineShape.java index 1369061d3..fb0ff6a7e 100644 --- a/src/jogl/classes/com/jogamp/graph/curve/OutlineShape.java +++ b/src/jogl/classes/com/jogamp/graph/curve/OutlineShape.java @@ -43,19 +43,32 @@ import com.jogamp.opengl.math.FloatUtil; import com.jogamp.opengl.math.VectorUtil; import com.jogamp.opengl.math.geom.AABBox; - /** * A Generic shape objects which is defined by a list of Outlines. * This Shape can be transformed to triangulations. * The list of triangles generated are render-able by a Region object. * The triangulation produced by this Shape will define the * closed region defined by the outlines. - * + * <p> * One or more OutlineShape Object can be associated to a region * this is left as a high-level representation of the Objects. For * optimizations, flexibility requirements for future features. - * - * <br><br> + * </p> + * <p> + * <a name="windingrules"> + * Outline shape general {@link Winding} rules + * <ul> + * <li>Outer boundary shapes are required as {@link Winding#CCW}, if unsure + * <ul> + * <li>You may check {@link Winding} via {@link #getWindingOfLastOutline()} or {@link Outline#getWinding()} (optional)</li> + * <li>Use {@link #setWindingOfLastOutline(Winding)} before {@link #closeLastOutline(boolean)} or {@link #closePath()} } to enforce {@link Winding#CCW}, or</li> + * <li>use {@link Outline#setWinding(Winding)} on a specific {@link Outline} to enforce {@link Winding#CCW}.</li> + * <li>If e.g. the {@link Winding} has changed for an {@link Outline} by above operations, its vertices have been reversed.</li> + * </ul></li> + * <li>Inner shapes or holes are adjusted to be {@link Winding#CW}, no user consideration is required here.</li> + * <li>Safe path: Simply create all shapes with {@link Winding#CCW} or apply {@link Outline#setWinding(Winding)}.</li> + * </ul> + * </p> * Example to creating an Outline Shape: * <pre> addVertex(...) @@ -67,33 +80,35 @@ import com.jogamp.opengl.math.geom.AABBox; addVertex(...) * </pre> * + * <p> * 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. - * <br> - * + * </p> + * <p> * 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). - * <br> + * </p> + * <p> * 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. - * - * <br>Example: <br> + * </p> + * Example: * <pre> addVertex(0,0, true); addVertex(0,1, false); addVertex(1,1, false); addVertex(1,0, true); * </pre> - * + * <p> * The above snippet defines a cubic nurbs curve where (0,1 and 1,1) * do not belong to the final rendered shape. + * </p> * * <i>Implementation Notes:</i><br> * <ul> * <li> The first vertex of any outline belonging to the shape should be on-curve</li> * <li> Intersections between off-curved parts of the outline is not handled</li> - * <li> Outline shape winding shall be constructed counter clock wise ({@link Winding#CCW}).</li> * </ul> * * @see Outline @@ -226,6 +241,21 @@ public final class OutlineShape implements Comparable<OutlineShape> { } /** + * Compute the {@link Winding} of the {@link #getLastOutline()} using the {@link #area(ArrayList)} function over all of its vertices. + * @return {@link Winding#CCW} or {@link Winding#CW} + */ + public final Winding getWindingOfLastOutline() { + return getLastOutline().getWinding(); + } + + /** + * Sets the enforced {@link Winding} of the {@link #getLastOutline()}. + */ + public final void setWindingOfLastOutline(final Winding enforced) { + getLastOutline().setWinding(enforced); + } + + /** * Add a new empty {@link Outline} * to the end of this shape's outline list. * <p>If the {@link #getLastOutline()} is empty already, no new one will be added.</p> @@ -358,9 +388,8 @@ public final class OutlineShape implements Comparable<OutlineShape> { /** * Adds a vertex to the last open outline to the shape's tail. * - * The constructed shape should be {@link Winding#CCW}. - * * @param v the vertex to be added to the OutlineShape + * @see <a href="#windingrules">see winding rules</a> */ public final void addVertex(final Vertex v) { final Outline lo = getLastOutline(); @@ -375,10 +404,9 @@ public final class OutlineShape implements Comparable<OutlineShape> { /** * Adds a vertex to the last open outline to the shape at {@code position} * - * The constructed shape should be {@link Winding#CCW}. - * * @param position index within the last open outline, at which the vertex will be added * @param v the vertex to be added to the OutlineShape + * @see <a href="#windingrules">see winding rules</a> */ public final void addVertex(final int position, final Vertex v) { final Outline lo = getLastOutline(); @@ -393,12 +421,10 @@ public final class OutlineShape implements Comparable<OutlineShape> { * Add a 2D {@link Vertex} to the last open outline to the shape's tail. * The 2D vertex will be represented as Z=0. * - * The constructed shape should be {@link Winding#CCW}. - * * @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. + * @param onCurve flag if this vertex is on the final curve or defines a curved region of the shape around this vertex. + * @see <a href="#windingrules">see winding rules</a> */ public final void addVertex(final float x, final float y, final boolean onCurve) { addVertex(vertexFactory.create(x, y, 0f, onCurve)); @@ -408,13 +434,11 @@ public final class OutlineShape implements Comparable<OutlineShape> { * Add a 2D {@link Vertex} to the last open outline to the shape at {@code position}. * The 2D vertex will be represented as Z=0. * - * The constructed shape should be {@link Winding#CCW}. - * * @param position index within the last open outline, at which the vertex will be added * @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. + * @param onCurve flag if this vertex is on the final curve or defines a curved region of the shape around this vertex. + * @see <a href="#windingrules">see winding rules</a> */ public final void addVertex(final int position, final float x, final float y, final boolean onCurve) { addVertex(position, vertexFactory.create(x, y, 0f, onCurve)); @@ -423,13 +447,11 @@ public final class OutlineShape implements Comparable<OutlineShape> { /** * Add a 3D {@link Vertex} to the last open outline to the shape's tail. * - * The constructed shape should be {@link Winding#CCW}. - * * @param x the x coordinate * @param y the y coordinate * @param z the z coordinate - * @param onCurve flag if this vertex is on the final curve or defines a curved region - * of the shape around this vertex. + * @param onCurve flag if this vertex is on the final curve or defines a curved region of the shape around this vertex. + * @see <a href="#windingrules">see winding rules</a> */ public final void addVertex(final float x, final float y, final float z, final boolean onCurve) { addVertex(vertexFactory.create(x, y, z, onCurve)); @@ -438,14 +460,12 @@ public final class OutlineShape implements Comparable<OutlineShape> { /** * Add a 3D {@link Vertex} to the last open outline to the shape at {@code position}. * - * The constructed shape should be {@link Winding#CCW}. - * * @param position index within the last open outline, at which the vertex will be added * @param x the x coordinate * @param y the y coordniate * @param z the z coordinate - * @param onCurve flag if this vertex is on the final curve or defines a curved region - * of the shape around this vertex. + * @param onCurve flag if this vertex is on the final curve or defines a curved region of the shape around this vertex. + * @see <a href="#windingrules">see winding rules</a> */ public final void addVertex(final int position, final float x, final float y, final float z, final boolean onCurve) { addVertex(position, vertexFactory.create(x, y, z, onCurve)); @@ -454,8 +474,6 @@ public final class OutlineShape implements Comparable<OutlineShape> { /** * Add a vertex to the last open outline to the shape's tail. * - * The constructed shape should be {@link Winding#CCW}. - * * The vertex is passed as a float array and its offset where its attributes are located. * The attributes should be continuous (stride = 0). * Attributes which value are not set (when length less than 3) @@ -463,8 +481,8 @@ public final class OutlineShape implements Comparable<OutlineShape> { * @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. + * @param onCurve flag if this vertex is on the final curve or defines a curved region of the shape around this vertex. + * @see <a href="#windingrules">see winding rules</a> */ public final void addVertex(final float[] coordsBuffer, final int offset, final int length, final boolean onCurve) { addVertex(vertexFactory.create(coordsBuffer, offset, length, onCurve)); @@ -473,8 +491,6 @@ public final class OutlineShape implements Comparable<OutlineShape> { /** * Add a vertex to the last open outline to the shape at {@code position}. * - * The constructed shape should be {@link Winding#CCW}. - * * The vertex is passed as a float array and its offset where its attributes are located. * The attributes should be continuous (stride = 0). * Attributes which value are not set (when length less than 3) @@ -483,8 +499,8 @@ public final class OutlineShape implements Comparable<OutlineShape> { * @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. + * @param onCurve flag if this vertex is on the final curve or defines a curved region of the shape around this vertex. + * @see <a href="#windingrules">see winding rules</a> */ public final void addVertex(final int position, final float[] coordsBuffer, final int offset, final int length, final boolean onCurve) { addVertex(position, vertexFactory.create(coordsBuffer, offset, length, onCurve)); @@ -659,13 +675,12 @@ public final class OutlineShape implements Comparable<OutlineShape> { /** * Start a new position for the next line segment at given point x/y (P1). * - * The constructed shape should be {@link Winding#CCW}. - * * @param x point (P1) * @param y point (P1) * @param z point (P1) * @see Path2F#moveTo(float, float) * @see #addPath(com.jogamp.graph.geom.plane.Path2F.Iterator, boolean) + * @see <a href="#windingrules">see winding rules</a> */ public final void moveTo(final float x, final float y, final float z) { if ( 0 == getLastOutline().getVertexCount() ) { @@ -680,13 +695,12 @@ public final class OutlineShape implements Comparable<OutlineShape> { /** * Add a line segment, intersecting the last point and the given point x/y (P1). * - * The constructed shape should be {@link Winding#CCW}. - * * @param x final point (P1) * @param y final point (P1) * @param z final point (P1) * @see Path2F#lineTo(float, float) * @see #addPath(com.jogamp.graph.geom.plane.Path2F.Iterator, boolean) + * @see <a href="#windingrules">see winding rules</a> */ public final void lineTo(final float x, final float y, final float z) { addVertex(x, y, z, true); @@ -695,8 +709,6 @@ public final class OutlineShape implements Comparable<OutlineShape> { /** * Add a quadratic curve segment, intersecting the last point and the second given point x2/y2 (P2). * - * The constructed shape should be {@link Winding#CCW}. - * * @param x1 quadratic parametric control point (P1) * @param y1 quadratic parametric control point (P1) * @param z1 quadratic parametric control point (P1) @@ -705,6 +717,7 @@ public final class OutlineShape implements Comparable<OutlineShape> { * @param z2 quadratic parametric control point (P2) * @see Path2F#quadTo(float, float, float, float) * @see #addPath(com.jogamp.graph.geom.plane.Path2F.Iterator, boolean) + * @see <a href="#windingrules">see winding rules</a> */ public final void quadTo(final float x1, final float y1, final float z1, final float x2, final float y2, final float z2) { addVertex(x1, y1, z1, false); @@ -714,8 +727,6 @@ public final class OutlineShape implements Comparable<OutlineShape> { /** * Add a cubic Bézier curve segment, intersecting the last point and the second given point x3/y3 (P3). * - * The constructed shape should be {@link Winding#CCW}. - * * @param x1 Bézier control point (P1) * @param y1 Bézier control point (P1) * @param z1 Bézier control point (P1) @@ -727,6 +738,7 @@ public final class OutlineShape implements Comparable<OutlineShape> { * @param z3 final interpolated control point (P3) * @see Path2F#cubicTo(float, float, float, float, float, float) * @see #addPath(com.jogamp.graph.geom.plane.Path2F.Iterator, boolean) + * @see <a href="#windingrules">see winding rules</a> */ public final void cubicTo(final float x1, final float y1, final float z1, final float x2, final float y2, final float z2, final float x3, final float y3, final float z3) { addVertex(x1, y1, z1, false); diff --git a/src/jogl/classes/com/jogamp/graph/geom/Outline.java b/src/jogl/classes/com/jogamp/graph/geom/Outline.java index b18d51849..7c9cb69c9 100644 --- a/src/jogl/classes/com/jogamp/graph/geom/Outline.java +++ b/src/jogl/classes/com/jogamp/graph/geom/Outline.java @@ -30,6 +30,7 @@ package com.jogamp.graph.geom; import java.util.ArrayList; import com.jogamp.graph.geom.plane.AffineTransform; +import com.jogamp.graph.geom.plane.Winding; import com.jogamp.graph.curve.OutlineShape; import com.jogamp.graph.curve.Region; import com.jogamp.opengl.math.FloatUtil; @@ -54,6 +55,8 @@ public class Outline implements Comparable<Outline> { private boolean closed; private final AABBox bbox; private boolean dirtyBBox; + private Winding winding; + private boolean dirtyWinding; /**Create an outline defined by control vertices. * An outline can contain off Curve vertices which define curved @@ -64,14 +67,19 @@ public class Outline implements Comparable<Outline> { closed = false; bbox = new AABBox(); dirtyBBox = false; + winding = Winding.CCW; + dirtyWinding = false; } /** * Copy ctor */ public Outline(final Outline src) { - vertices = new ArrayList<Vertex>(src.vertices.size()); - for(int i=0; i<vertices.size(); i++) { + final int count = src.vertices.size(); + vertices = new ArrayList<Vertex>(count); + winding = src.getWinding(); + dirtyWinding = false; + for(int i=0; i<count; i++) { vertices.add( src.vertices.get(i).clone() ); } closed = src.closed; @@ -79,6 +87,74 @@ public class Outline implements Comparable<Outline> { dirtyBBox = src.dirtyBBox; } + /** + * Copy ctor w/ enforced Winding + * <p> + * If the enforced {@link Winding} doesn't match the source Outline, the vertices reversed copied into this new instance. + * </p> + * @param src the source Outline + * @param enforce {@link Winding} to be enforced on this copy + */ + public Outline(final Outline src, final Winding enforce) { + final int count = src.vertices.size(); + vertices = new ArrayList<Vertex>(count); + final Winding had_winding = src.getWinding();; + winding = had_winding; + dirtyWinding = false; + if( enforce != had_winding ) { + for(int i=count-1; i>=0; --i) { + vertices.add( src.vertices.get(i).clone() ); + } + winding = enforce; + } else { + for(int i=0; i<count; ++i) { + vertices.add( src.vertices.get(i).clone() ); + } + } + closed = src.closed; + bbox = new AABBox(src.bbox); + dirtyBBox = src.dirtyBBox; + } + + /** + * Sets {@link Winding} to this outline + * <p> + * If the enforced {@link Winding} doesn't match this Outline, the vertices are reversed. + * </p> + * @param enforce to be enforced {@link Winding} + */ + public final void setWinding(final Winding enforce) { + final Winding had_winding = getWinding(); + if( enforce != had_winding ) { + final int count = vertices.size(); + final ArrayList<Vertex> ccw = new ArrayList<Vertex>(count); + for(int i=count-1; i>=0; --i) { + ccw.add(vertices.get(i)); + } + vertices = ccw; + winding = enforce; + } + } + + /** + * Compute the winding of the {@link #getLastOutline()} using the {@link #area(ArrayList)} function over all of its vertices. + * @return {@link Winding#CCW} or {@link Winding#CW} + */ + public final Winding getWinding() { + if( !dirtyWinding ) { + return winding; + } + final int count = getVertexCount(); + if( 3 > count ) { + winding = Winding.CCW; + } else { + final ArrayList<Vertex> vertices = getVertices(); + winding = VectorUtil.getWinding(vertices); + } + dirtyWinding = false; + return winding; + } + public final int getVertexCount() { return vertices.size(); } @@ -107,6 +183,7 @@ public class Outline implements Comparable<Outline> { if(!dirtyBBox) { bbox.resize(vertex.getCoord()); } + dirtyWinding = true; } /** Replaces the {@link Vertex} element at the given {@code position}. @@ -123,6 +200,7 @@ public class Outline implements Comparable<Outline> { } vertices.set(position, vertex); dirtyBBox = true; + dirtyWinding = true; } public final Vertex getVertex(final int index){ @@ -141,6 +219,7 @@ public class Outline implements Comparable<Outline> { */ public final Vertex removeVertex(final int position) throws IndexOutOfBoundsException { dirtyBBox = true; + dirtyWinding = true; return vertices.remove(position); } diff --git a/src/jogl/classes/com/jogamp/opengl/math/VectorUtil.java b/src/jogl/classes/com/jogamp/opengl/math/VectorUtil.java index 3ee504a29..d7e72e245 100644 --- a/src/jogl/classes/com/jogamp/opengl/math/VectorUtil.java +++ b/src/jogl/classes/com/jogamp/opengl/math/VectorUtil.java @@ -888,25 +888,35 @@ public final class VectorUtil { return triAreaVec2(a,b,c) > 0; } - /** Compute the winding of given points + /** + * Compute the winding of the 3 given points + * <p> + * Consider using {@link #getWinding(ArrayList)} using the {@link #area(ArrayList)} function over all points + * on complex shapes for a reliable result! + * </p> * @param a first vertex * @param b second vertex * @param c third vertex - * @return Winding + * @return {@link Winding#CCW} or {@link Winding#CW} + * @see #getWinding(ArrayList) */ public static Winding getWinding(final Vert2fImmutable a, final Vert2fImmutable b, final Vert2fImmutable c) { return triAreaVec2(a,b,c) > 0 ? Winding.CCW : Winding.CW ; } - /** Computes the area of a list of vertices to check if ccw + /** + * Computes the area of a list of vertices. + * <p> + * This method is utilized e.g. to reliably compute the {@link Winding} of complex shapes. + * </p> * @param vertices * @return positive area if ccw else negative area value + * @see #getWinding(ArrayList) */ public static float area(final ArrayList<? extends Vert2fImmutable> vertices) { final int n = vertices.size(); float area = 0.0f; - for (int p = n - 1, q = 0; q < n; p = q++) - { + for (int p = n - 1, q = 0; q < n; p = q++) { final float[] pCoord = vertices.get(p).getCoord(); final float[] qCoord = vertices.get(q).getCoord(); area += pCoord[0] * qCoord[1] - qCoord[0] * pCoord[1]; @@ -914,9 +924,15 @@ public final class VectorUtil { return area; } - /** Compute the general winding of the vertices + /** + * Compute the winding using the {@link #area(ArrayList)} function over all vertices for complex shapes. + * <p> + * Uses the {@link #area(ArrayList)} function over all points + * on complex shapes for a reliable result! + * </p> * @param vertices array of Vertices - * @return CCW or CW {@link Winding} + * @return {@link Winding#CCW} or {@link Winding#CW} + * @see #area(ArrayList) */ public static Winding getWinding(final ArrayList<? extends Vert2fImmutable> vertices) { return area(vertices) >= 0 ? Winding.CCW : Winding.CW ; |