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:
      - Constant Field Values

  - ### 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:
      - Constant Field Values

  - ### VERB_MOVE

    public static final byte VERB_MOVE
    Primitive commands of path segments.
    See Also:
      - Constant Field Values

  - ### VERB_LINE

    public static final byte VERB_LINE
    Primitive commands of path segments.
    See Also:
      - Constant Field Values

  - ### VERB_QUAD

    public static final byte VERB_QUAD
    Primitive commands of path segments.
    See Also:
      - Constant Field Values

  - ### VERB_CUBIC

    public static final byte VERB_CUBIC
    Primitive commands of path segments.
    See Also:
      - Constant Field Values

  - ### VERB_CLOSE

    public static final byte VERB_CLOSE
    Primitive commands of path segments.
    See Also:
      - Constant Field Values

  - ### DIRECTION_CW

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

  - ### 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:
      - Constant Field Values

  - ### SEGMENT_LINE

    public static final int SEGMENT_LINE
    See Also:
      - Constant Field Values

  - ### SEGMENT_QUAD

    public static final int SEGMENT_QUAD
    See Also:
      - Constant Field Values

  - ### SEGMENT_CUBIC

    public static final int SEGMENT_CUBIC
    See Also:
      - Constant Field Values

  - ### APPROXIMATE_ARC_WITH_CUBICS

    public static final int APPROXIMATE_ARC_WITH_CUBICS
    See Also:
      - Constant Field Values

  - ### APPROXIMATE_CONIC_WITH_QUADS

    public static final int APPROXIMATE_CONIC_WITH_QUADS
    See Also:
      - Constant Field Values

- ## 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:
      - `PathIterator.FILL_EVEN_ODD`
      - `PathIterator.FILL_NON_ZERO`

  - ### 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:
      - `isFinite()`

  - ### 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`