Class OutlineShape

  • All Implemented Interfaces:
    Comparable<OutlineShape>

    public final class OutlineShape
    extends Object
    implements Comparable<OutlineShape>
    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.

    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.

    Outline shape general Winding rules

    Example to creating an Outline Shape:
          addVertex(...)
          addVertex(...)
          addVertex(...)
          addEmptyOutline()
          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:
    • The first vertex of any outline belonging to the shape should be on-curve
    • Intersections between off-curved parts of the outline is not handled
    See Also:
    Outline, Region
    • Constructor Detail

      • OutlineShape

        public OutlineShape()
        Create a new Outline based Shape
    • Method Detail

      • getSharpness

        public final float getSharpness()
        Sharpness value, defaults to DEFAULT_SHARPNESS.
      • setSharpness

        public final void setSharpness​(float s)
        Sets sharpness, defaults to DEFAULT_SHARPNESS.
      • clear

        public final void clear()
        Clears all data and reset all states as if this instance was newly created
      • getOutlineCount

        public final int getOutlineCount()
        Returns the number of Outlines.
      • getVertexCount

        public final int getVertexCount()
        Returns the total vertex number of all Outlines.
      • addEmptyOutline

        public final void addEmptyOutline()
        Add a new empty Outline to the end of this shape's outline list.

        If the getLastOutline() is empty already, no new one will be added.

        After a call to this function all new vertices added will belong to the new outline
      • addOutline

        public final void addOutline​(Outline outline)
                              throws NullPointerException
        Appends the Outline element to the end, ensuring a clean tail.

        A clean tail is ensured, no double empty Outlines are produced and a pre-existing empty outline will be replaced with the given one.

        Parameters:
        outline - Outline object to be added
        Throws:
        NullPointerException - if the Outline element is null
      • addOutline

        public final void addOutline​(int position,
                                     Outline outline)
                              throws NullPointerException,
                                     IndexOutOfBoundsException
        Insert the Outline element at the given position.

        If the position indicates the end of this list, a clean tail is ensured, no double empty Outlines are produced and a pre-existing empty outline will be replaced with the given one.

        Parameters:
        position - of the added Outline
        outline - Outline object to be added
        Throws:
        NullPointerException - if the Outline element is null
        IndexOutOfBoundsException - if position is out of range (position < 0 || position > getOutlineNumber())
      • removeOutline

        public final Outline removeOutline​(int position)
                                    throws IndexOutOfBoundsException
        Removes the Outline element at the given position.

        Sets the bounding box dirty, hence a next call to getBounds() will validate it.

        Parameters:
        position - of the to be removed Outline
        Throws:
        IndexOutOfBoundsException - if position is out of range (position < 0 || position >= getOutlineNumber())
      • getLastOutline

        public final Outline getLastOutline()
        Get the last added outline to the list of outlines that define the shape
        Returns:
        the last outline
      • addVertex

        public final void addVertex​(Vertex v)
        Adds a vertex to the last open outline to the shape's tail.
        Parameters:
        v - the vertex to be added to the OutlineShape
        See Also:
        see winding rules
      • addVertex

        public final void addVertex​(int position,
                                    Vertex v)
        Adds a vertex to the last open outline to the shape at position
        Parameters:
        position - index within the last open outline, at which the vertex will be added
        v - the vertex to be added to the OutlineShape
        See Also:
        see winding rules
      • addVertex

        public final void addVertex​(float x,
                                    float y,
                                    boolean onCurve)
        Add a 2D Vertex to the last open outline to the shape's tail. The 2D vertex will be represented as Z=0.
        Parameters:
        x - the x coordinate
        y - the y coordniate
        onCurve - flag if this vertex is on the final curve or defines a curved region of the shape around this vertex.
        See Also:
        see winding rules
      • addVertex

        public final void addVertex​(int position,
                                    float x,
                                    float y,
                                    boolean onCurve)
        Add a 2D Vertex to the last open outline to the shape at position. The 2D vertex will be represented as Z=0.
        Parameters:
        position - index within the last open outline, at which the vertex will be added
        x - the x coordinate
        y - the y coordniate
        onCurve - flag if this vertex is on the final curve or defines a curved region of the shape around this vertex.
        See Also:
        see winding rules
      • addVertex

        public final void addVertex​(float x,
                                    float y,
                                    float z,
                                    boolean onCurve)
        Add a 3D Vertex to the last open outline to the shape's tail.
        Parameters:
        x - the x coordinate
        y - the y coordinate
        z - the z coordinate
        onCurve - flag if this vertex is on the final curve or defines a curved region of the shape around this vertex.
        See Also:
        see winding rules
      • addVertex

        public final void addVertex​(int position,
                                    float x,
                                    float y,
                                    float z,
                                    boolean onCurve)
        Add a 3D Vertex to the last open outline to the shape at position.
        Parameters:
        position - index within the last open outline, at which the vertex will be added
        x - the x coordinate
        y - the y coordniate
        z - the z coordinate
        onCurve - flag if this vertex is on the final curve or defines a curved region of the shape around this vertex.
        See Also:
        see winding rules
      • addVertex

        public final void addVertex​(float[] coordsBuffer,
                                    int offset,
                                    int length,
                                    boolean onCurve)
        Add a vertex to the last open outline to the shape's tail. 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) are set implicitly to zero.
        Parameters:
        coordsBuffer - the coordinate array where the vertex attributes are to be picked from
        offset - the offset in the buffer to the x coordinate
        length - the number of attributes to pick from the buffer (maximum 3)
        onCurve - flag if this vertex is on the final curve or defines a curved region of the shape around this vertex.
        See Also:
        see winding rules
      • addVertex

        public final void addVertex​(int position,
                                    float[] coordsBuffer,
                                    int offset,
                                    int length,
                                    boolean onCurve)
        Add a vertex to the last open outline to the shape at position. 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) are set implicitly to zero.
        Parameters:
        position - index within the last open outline, at which the vertex will be added
        coordsBuffer - the coordinate array where the vertex attributes are to be picked from
        offset - the offset in the buffer to the x coordinate
        length - the number of attributes to pick from the buffer (maximum 3)
        onCurve - flag if this vertex is on the final curve or defines a curved region of the shape around this vertex.
        See Also:
        see winding rules
      • closeLastOutline

        public final void closeLastOutline​(boolean closeTail)
        Closes the last outline in the shape.

        Checks whether the last vertex equals to the first of the last outline. If not equal, it either appends a clone of the first vertex or prepends a clone of the last vertex, depending on closeTail.

        Parameters:
        closeTail - if true, a clone of the first vertex will be appended, otherwise a clone of the last vertex will be prepended.
      • addPath

        public void addPath​(Path2F path,
                            boolean connect)
        Append the given path geometry to this outline shape. The given path geometry should be Winding.CCW. If the given path geometry is Winding.CW, use addPathRev(Path2F, boolean).
        Parameters:
        path - the Path2F to append to this outline shape, should be Winding.CCW.
        connect - pass true to turn an initial moveTo segment into a lineTo segment to connect the new geometry to the existing path, otherwise pass false.
        See Also:
        Path2F.getWinding()
      • addPath

        public final void addPath​(Path2F.Iterator pathI,
                                  boolean connect)
        Add the given Path2F.Iterator to this outline shape. The given path geometry should be Winding.CCW. If the given path geometry is Winding.CW, use {@link #addPathRev(Path2F.Iterator, boolean).
        Parameters:
        pathI - the Path2F.Iterator to append to this outline shape, should be Winding.CCW.
        connect - pass true to turn an initial moveTo segment into a lineTo segment to connect the new geometry to the existing path, otherwise pass false.
        See Also:
        Path2F.Iterator.getWinding()
      • addPathRev

        public void addPathRev​(Path2F path,
                               boolean connect)
        Append the given path geometry to this outline shape in reverse order. The given path geometry should be Winding.CW. If the given path geometry is Winding.CCW, use addPath(Path2F, boolean).
        Parameters:
        path - the Path2F to append to this outline shape, should be Winding.CW.
        connect - pass true to turn an initial moveTo segment into a lineTo segment to connect the new geometry to the existing path, otherwise pass false.
      • addPathRev

        public final void addPathRev​(Path2F.Iterator pathI,
                                     boolean connect)
        Add the given Path2F.Iterator to this outline shape in reverse order. The given path geometry should be Winding.CW. If the given path geometry is Winding.CCW, use {@link #addPath(Path2F.Iterator, boolean).
        Parameters:
        pathI - the Path2F.Iterator to append to this outline shape, should be Winding.CW.
        connect - pass true to turn an initial moveTo segment into a lineTo segment to connect the new geometry to the existing path, otherwise pass false.
      • quadTo

        public final void quadTo​(float x1,
                                 float y1,
                                 float z1,
                                 float x2,
                                 float y2,
                                 float z2)
        Add a quadratic curve segment, intersecting the last point and the second given point x2/y2 (P2).
        Parameters:
        x1 - quadratic parametric control point (P1)
        y1 - quadratic parametric control point (P1)
        z1 - quadratic parametric control point (P1)
        x2 - final interpolated control point (P2)
        y2 - final interpolated control point (P2)
        z2 - quadratic parametric control point (P2)
        See Also:
        Path2F.quadTo(float, float, float, float), addPath(com.jogamp.graph.geom.plane.Path2F.Iterator, boolean), see winding rules
      • cubicTo

        public final void cubicTo​(float x1,
                                  float y1,
                                  float z1,
                                  float x2,
                                  float y2,
                                  float z2,
                                  float x3,
                                  float y3,
                                  float z3)
        Add a cubic Bézier curve segment, intersecting the last point and the second given point x3/y3 (P3).
        Parameters:
        x1 - Bézier control point (P1)
        y1 - Bézier control point (P1)
        z1 - Bézier control point (P1)
        x2 - Bézier control point (P2)
        y2 - Bézier control point (P2)
        z2 - Bézier control point (P2)
        x3 - final interpolated control point (P3)
        y3 - final interpolated control point (P3)
        z3 - final interpolated control point (P3)
        See Also:
        Path2F.cubicTo(float, float, float, float, float, float), addPath(com.jogamp.graph.geom.plane.Path2F.Iterator, boolean), see winding rules
      • getVertices

        public final ArrayList<Vertex> getVertices()
        Return list of concatenated vertices associated with all Outlines of this object.

        Vertices are cached until marked dirty.

        Should always be called after getTriangles(VerticesState), since the latter will mark all cached vertices dirty!

      • getTriangles

        public final ArrayList<Triangle> getTriangles​(OutlineShape.VerticesState destinationType)
        Triangulate the OutlineShape generating a list of triangles, while #transformOutlines(VerticesState) beforehand.

        Triangles are cached until marked dirty.

        Returns:
        an arraylist of triangles representing the filled region which is produced by the combination of the outlines
      • transform

        public final OutlineShape transform​(AffineTransform t)
        Return a transformed instance with all Outlines are copied and transformed.

        Note: Triangulated data is lost in returned instance!

      • getBounds

        public final AABBox getBounds()
      • equals

        public final boolean equals​(Object obj)
        Overrides:
        equals in class Object
        Parameters:
        obj - the Object to compare this OutlineShape with
        Returns:
        true if obj is an OutlineShape, not null, same outlineState, equal bounds and equal outlines in the same order
      • hashCode

        public final int hashCode()
        Overrides:
        hashCode in class Object