Package icyllis.arc3d.core

Class Path

java.lang.Object
icyllis.arc3d.core.Path
All Implemented Interfaces:
PathConsumer, PathIterable
Direct Known Subclasses:
Path
public class Path extends Object implements PathIterable, PathConsumer
The Path object contains mutable path elements.

Path may be empty, or contain one or more verbs that outline a figure. Path always starts with a move verb to a Cartesian coordinate, and may be followed by additional verbs that add lines or curves. Adding a close verb makes the geometry into a continuous loop, a closed contour. Path may contain any number of contours, each beginning with a move verb.

Path contours may contain only a move verb, or may also contain lines, quadratic Béziers, and cubic Béziers. Path contours may be open or closed.

When used to draw a filled area, Path describes whether the fill is inside or outside the geometry. Path also describes the winding rule used to fill overlapping contours.

Note: Path lazily computes metrics likes bounds and convexity. Call updateBoundsCache() to make path thread safe.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static @interface 
    Path.FillRule
     
    class 
    Path.RawIterator
    Low-level access to path elements.
    static @interface 
    Path.SegmentMask
    Segment constants correspond to each drawing verb type in path; for instance, if path contains only lines, only the Line bit is set.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    APPROXIMATE_ARC_WITH_CUBICS
     
    static final int
    APPROXIMATE_CONIC_WITH_QUADS
     
    static final int
    DIRECTION_CCW
    Counter-clockwise direction for adding closed contours, assumes the origin is top left, y-down.
    static final int
    DIRECTION_CW
    Clockwise direction for adding closed contours, assumes the origin is top left, y-down.
    static final int
    FILL_EVEN_ODD
    The fill rule constant for specifying an even-odd rule for determining the interior of a path.
    The even-odd rule specifies that a point lies inside the path if a ray drawn in any direction from that point to infinity is crossed by path segments an odd number of times.
    static final int
    FILL_NON_ZERO
    The fill rule constant for specifying a non-zero rule for determining the interior of a path.
    The non-zero rule specifies that a point lies inside the path if a ray drawn in any direction from that point to infinity is crossed by path segments a different number of times in the counter-clockwise direction than the clockwise direction.
    static final int
    SEGMENT_CUBIC
     
    static final int
    SEGMENT_LINE
     
    static final int
    SEGMENT_QUAD
     
    static final byte
    VERB_CLOSE
    Primitive commands of path segments.
    static final byte
    VERB_CUBIC
    Primitive commands of path segments.
    static final byte
    VERB_LINE
    Primitive commands of path segments.
    static final byte
    VERB_MOVE
    Primitive commands of path segments.
    static final byte
    VERB_QUAD
    Primitive commands of path segments.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Path()
    Creates an empty Path with a default fill rule of FILL_NON_ZERO.
    Path(Path other)
    Creates a copy of an existing Path object.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clear()
    Resets the path to its initial state, clears points and verbs and sets fill rule to FILL_NON_ZERO.
    void
    close()
    Closes the current contour by drawing a straight line back to the point of the last moveTo(float, float).
    int
    countPoints()
    Returns the number of points (x,y pairs) in path.
    int
    countVerbs()
    Returns the number of verbs added to path.
    void
    cubicTo(float x1, float y1, float x2, float y2, float x3, float y3)
    Adds a curved segment, defined by three new points, to the path by drawing a cubic Bézier curve that intersects both the current point and the specified point (x3,y3), using the specified points (x1,y1) and (x2,y2) as cubic control points.
    void
    cubicToRel(float dx1, float dy1, float dx2, float dy2, float dx3, float dy3)
    Relative version of "cubic to".
    void
    done()
    Called after the last segment of the last sub-path when the iteration of the path segments is completely done.
    boolean
    equals(Object obj)
     
    long
    estimatedByteSize()
    Returns the estimated byte size of path object in memory.
    void
    forEach(PathConsumer action)
    Iterates the Path and feeds the given consumer.
    Rect2fc
    getBounds()
    Returns minimum and maximum axes values of coordinates.
    void
    getBounds(Rect2f dst)
    Helper method to getBounds(), stores the result to dst.
    int
    getFillRule()
    Returns the rule used to fill path.
    PathIterator
    getPathIterator()
     
    int
    getSegmentMask()
    Returns a mask, where each set bit corresponds to a Segment constant if path contains one or more verbs of that type.
    int
    hashCode()
     
    boolean
    isEmpty()
    Returns true if path has no point and verb.
    boolean
    isFinite()
    Returns false for any coordinate value of infinity or NaN.
    void
    lineTo(float x, float y)
    Adds a point to the path by drawing a straight line from the current point to the new specified point (x,y).
    void
    lineToRel(float dx, float dy)
    Relative version of "line to".
    void
    move(Path other)
    Moves contents from other path into this path.
    void
    moveTo(float x, float y)
    Adds a point to the path by moving to the specified point (x,y).
    void
    moveToRel(float dx, float dy)
    Relative version of "move to".
    void
    quadTo(float x1, float y1, float x2, float y2)
    Adds a curved segment, defined by two new points, to the path by drawing a quadratic Bézier curve that intersects both the current point and the specified point (x2,y2), using the specified point (x1,y1) as a quadratic control point.
    void
    quadToRel(float dx1, float dy1, float dx2, float dy2)
    Relative version of "quad to".
    void
    recycle()
    Resets the path to its initial state, clears points and verbs and sets fill rule to FILL_NON_ZERO.
    void
    reset()
    Resets the path to its initial state, clears points and verbs and sets fill rule to FILL_NON_ZERO.
    void
    set(Path other)
    Creates a copy of an existing Path object.
    void
    setFillRule(int rule)
    Sets the rule used to fill path.
    void
    transform(Matrixc matrix)
    Transforms verb array, Point array, and weight by matrix.
    void
    transform(Matrixc matrix, Path dst)
    Transforms verb array, point array, and weight by matrix.
    void
    trimToSize()
    Trims the internal storage to the current size.
    void
    updateBoundsCache()
    Updates internal bounds so that subsequent calls to getBounds() are instantaneous.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

    Methods inherited from interface icyllis.arc3d.core.PathConsumer

    cubicTo, quadTo

  • Field Details

    • FILL_NON_ZERO

      public static final int FILL_NON_ZERO
      The fill rule constant for specifying a non-zero rule for determining the interior of a path.
      The non-zero rule specifies that a point lies inside the path if a ray drawn in any direction from that point to infinity is crossed by path segments a different number of times in the counter-clockwise direction than the clockwise direction.
      See Also:

    • FILL_EVEN_ODD

      public static final int FILL_EVEN_ODD
      The fill rule constant for specifying an even-odd rule for determining the interior of a path.
      The even-odd rule specifies that a point lies inside the path if a ray drawn in any direction from that point to infinity is crossed by path segments an odd number of times.
      See Also:

    • VERB_MOVE

      public static final byte VERB_MOVE
      Primitive commands of path segments.
      See Also:

    • VERB_LINE

      public static final byte VERB_LINE
      Primitive commands of path segments.
      See Also:

    • VERB_QUAD

      public static final byte VERB_QUAD
      Primitive commands of path segments.
      See Also:

    • VERB_CUBIC

      public static final byte VERB_CUBIC
      Primitive commands of path segments.
      See Also:

    • VERB_CLOSE

      public static final byte VERB_CLOSE
      Primitive commands of path segments.
      See Also:

    • DIRECTION_CW

      public static final int DIRECTION_CW
      Clockwise direction for adding closed contours, assumes the origin is top left, y-down.
      See Also:

    • DIRECTION_CCW

      public static final int DIRECTION_CCW
      Counter-clockwise direction for adding closed contours, assumes the origin is top left, y-down.
      See Also:

    • SEGMENT_LINE

      public static final int SEGMENT_LINE
      See Also:

    • SEGMENT_QUAD

      public static final int SEGMENT_QUAD
      See Also:

    • SEGMENT_CUBIC

      public static final int SEGMENT_CUBIC
      See Also:

    • APPROXIMATE_ARC_WITH_CUBICS

      public static final int APPROXIMATE_ARC_WITH_CUBICS
      See Also:

    • APPROXIMATE_CONIC_WITH_QUADS

      public static final int APPROXIMATE_CONIC_WITH_QUADS
      See Also:

  • Constructor Details

    • Path

      public Path()
      Creates an empty Path with a default fill rule of FILL_NON_ZERO.

    • Path

      public Path(@Nonnull Path other)
      Creates a copy of an existing Path object.

      Internally, the two paths share reference values. The underlying verb array, coordinate array and weights are copied when modified.

  • Method Details

    • getFillRule

      public int getFillRule()
      Returns the rule used to fill path.
      Specified by:
      getFillRule in interface PathIterable
      Returns:
      current fill rule
      See Also:

    • setFillRule

      public void setFillRule(int rule)
      Sets the rule used to fill path. rule is either FILL_NON_ZERO or FILL_EVEN_ODD .

    • set

      public void set(@Nonnull Path other)
      Creates a copy of an existing Path object.

      Internally, the two paths share reference values. The underlying verb array, coordinate array and weights are copied when modified.

    • move

      public void move(@Nonnull Path other)
      Moves contents from other path into this path. This is equivalent to call this.set(other) and then other.recycle().

    • reset

      public void reset()
      Resets the path to its initial state, clears points and verbs and sets fill rule to FILL_NON_ZERO.

      Preserves internal storage if it's unique, otherwise discards.

    • clear

      public void clear()
      Resets the path to its initial state, clears points and verbs and sets fill rule to FILL_NON_ZERO.

      Preserves internal storage if it's unique, otherwise allocates new storage with the same size.

    • recycle

      public void recycle()
      Resets the path to its initial state, clears points and verbs and sets fill rule to FILL_NON_ZERO.

      This explicitly discards the internal storage, it is recommended to call when the path object will be no longer used.

    • trimToSize

      public void trimToSize()
      Trims the internal storage to the current size. This operation can minimize memory usage, see estimatedByteSize().

    • isEmpty

      public boolean isEmpty()
      Returns true if path has no point and verb. reset(), clear() and recycle() make path empty.
      Returns:
      true if the path contains no verb

    • isFinite

      public boolean isFinite()
      Returns false for any coordinate value of infinity or NaN.
      Returns:
      true if all point coordinates are finite

    • moveTo

      public void moveTo(float x, float y)
      Adds a point to the path by moving to the specified point (x,y). A new contour begins at (x,y).
      Specified by:
      moveTo in interface PathConsumer
      Parameters:
      x - the specified X coordinate
      y - the specified Y coordinate

    • moveToRel

      public void moveToRel(float dx, float dy)
      Relative version of "move to".
      Parameters:
      dx - offset from last point to contour start on x-axis
      dy - offset from last point to contour start on y-axis
      Throws:
      IllegalStateException - Path is empty

    • lineTo

      public void lineTo(float x, float y)
      Adds a point to the path by drawing a straight line from the current point to the new specified point (x,y).
      Specified by:
      lineTo in interface PathConsumer
      Parameters:
      x - the specified X coordinate
      y - the specified Y coordinate
      Throws:
      IllegalStateException - No contour

    • lineToRel

      public void lineToRel(float dx, float dy)
      Relative version of "line to".

      Adds a line from the last point to the specified vector (dx, dy).

      Parameters:
      dx - the offset from last point to line end on x-axis
      dy - the offset from last point to line end on y-axis

    • quadTo

      public void quadTo(float x1, float y1, float x2, float y2)
      Adds a curved segment, defined by two new points, to the path by drawing a quadratic Bézier curve that intersects both the current point and the specified point (x2,y2), using the specified point (x1,y1) as a quadratic control point.
      Specified by:
      quadTo in interface PathConsumer
      Parameters:
      x1 - the X coordinate of the quadratic control point
      y1 - the Y coordinate of the quadratic control point
      x2 - the X coordinate of the final end point
      y2 - the Y coordinate of the final end point

    • quadToRel

      public void quadToRel(float dx1, float dy1, float dx2, float dy2)
      Relative version of "quad to".

      Adds quad from last point towards vector (dx1, dy1), to vector (dx2, dy2).

      Parameters:
      dx1 - offset from last point to quad control on x-axis
      dy1 - offset from last point to quad control on y-axis
      dx2 - offset from last point to quad end on x-axis
      dy2 - offset from last point to quad end on y-axis

    • cubicTo

      public void cubicTo(float x1, float y1, float x2, float y2, float x3, float y3)
      Adds a curved segment, defined by three new points, to the path by drawing a cubic Bézier curve that intersects both the current point and the specified point (x3,y3), using the specified points (x1,y1) and (x2,y2) as cubic control points.
      Specified by:
      cubicTo in interface PathConsumer
      Parameters:
      x1 - the X coordinate of the first cubic control point
      y1 - the Y coordinate of the first cubic control point
      x2 - the X coordinate of the second cubic control point
      y2 - the Y coordinate of the second cubic control point
      x3 - the X coordinate of the final end point
      y3 - the Y coordinate of the final end point

    • cubicToRel

      public void cubicToRel(float dx1, float dy1, float dx2, float dy2, float dx3, float dy3)
      Relative version of "cubic to".

      Adds cubic from last point towards vector (dx1, dy1), vector (dx2, dy2), to vector (dx3, dy3).

      Parameters:
      dx1 - offset from last point to first cubic control on x-axis
      dy1 - offset from last point to first cubic control on y-axis
      dx2 - offset from last point to second cubic control on x-axis
      dy2 - offset from last point to second cubic control on y-axis
      dx3 - offset from last point to cubic end on x-axis
      dy3 - offset from last point to cubic end on y-axis

    • close

      public void close()
      Closes the current contour by drawing a straight line back to the point of the last moveTo(float, float). If the path is already closed then this method has no effect.
      Specified by:
      close in interface PathConsumer

    • done

      public void done()
      Description copied from interface: PathConsumer
      Called after the last segment of the last sub-path when the iteration of the path segments is completely done.
      Specified by:
      done in interface PathConsumer

    • transform

      public void transform(@Nonnull Matrixc matrix)
      Transforms verb array, Point array, and weight by matrix. transform may change verbs and increase their number. Path is replaced by transformed data.
      Parameters:
      matrix - Matrix to apply to Path

    • transform

      public void transform(@Nonnull Matrixc matrix, @Nullable Path dst)
      Transforms verb array, point array, and weight by matrix. transform may change verbs and increase their number. Transformed Path replaces dst; if dst is null, original data is replaced.
      Parameters:
      matrix - Matrix to apply to Path
      dst - overwritten, transformed copy of Path; may be null

    • countVerbs

      public int countVerbs()
      Returns the number of verbs added to path.
      Returns:
      size of verb list

    • countPoints

      public int countPoints()
      Returns the number of points (x,y pairs) in path.
      Returns:
      size of point list

    • getBounds

      @Nonnull public Rect2fc getBounds()
      Returns minimum and maximum axes values of coordinates. Returns empty if path contains no points or is not finite.

      Returned bounds includes all points added to path, including points associated with MOVE that define empty contours.

      This method returns a cached result; it is recalculated only after this path is altered.

      Returns:
      bounds of all points, read-only
      See Also:

    • getBounds

      public void getBounds(@Nonnull Rect2f dst)
      Helper method to getBounds(), stores the result to dst.

    • updateBoundsCache

      public void updateBoundsCache()
      Updates internal bounds so that subsequent calls to getBounds() are instantaneous. Unaltered copies of path may also access cached bounds through getBounds().

      For now, identical to calling getBounds() and ignoring the returned value.

      Call to prepare path subsequently drawn from multiple threads, to avoid a race condition where each draw separately computes the bounds.

    • getSegmentMask

      public int getSegmentMask()
      Returns a mask, where each set bit corresponds to a Segment constant if path contains one or more verbs of that type.

      This method returns a cached result; it is very fast.

      Returns:
      Segment bits or zero

    • getPathIterator

      @Nonnull public PathIterator getPathIterator()
      Specified by:
      getPathIterator in interface PathIterable

    • forEach

      public void forEach(@Nonnull PathConsumer action)
      Iterates the Path and feeds the given consumer.
      Specified by:
      forEach in interface PathIterable

    • estimatedByteSize

      public long estimatedByteSize()
      Returns the estimated byte size of path object in memory. This method does not take into account whether internal storage is shared or not.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object