Package edu.cornell.gdiac.math

Class PathExtruder

java.lang.Object
edu.cornell.gdiac.math.PathExtruder
public class PathExtruder extends Object
A factory class for extruding paths into a solid polygon.

An extrusion of a path is a polygon that follows the path but gives it width. Hence it takes a path and turns it into a solid shape. This is more complicated than simply triangulating the original path. The new polygon has more vertices,depending on the choice of joint (shape at the corners) and cap (shape at the end).

As with many of our factory classes, the methods are broken up into three phases: initialization, calculation, and materialization. To use the factory, you first set the data (in this case a set of vertices or Path2 object) with the initialization methods. You then call the calculation method. Finally, you use the materialization methods to access the data in several different ways.

This division allows us to support multithreaded calculation if the data generation takes too long. However, note that this factory is not thread safe in that you cannot access data while it is still in mid-calculation.

CREDITS: This code heavily inspired by NanoVG by Mikko Mononen (memon@inside.org), and the bulk of the algorithm is taken from that code. However it is has been altered and optimized according to extensive profiling.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    PathExtruder.EndCap
    The types of caps supported in an extrusion.
    static enum 
    PathExtruder.Joint
    The types of joints supported in an extrusion.

  • Constructor Summary

    Constructors
    Constructor
    Description
    PathExtruder()
    Creates an extruder with no path data.
    PathExtruder(float[] points, boolean closed)
    Creates an extruder with the given path.
    PathExtruder(Path2 path)
    Creates an extruder with the given path.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    calculate(float width)
    Performs a extrusion of the current path data.
    void
    calculate(float lWidth, float rWidth)
    Performs an asymmetric extrusion of the current path data.
    void
    clear()
    Clears all internal data, including initial vertex data.
    Path2[]
    getBorder()
    Returns a (closed) path representing the extrusion border(s)
    Path2[]
    getBorder(Path2[] buffer)
    Stores a (closed) path representing the extrusion border in the buffer
    PathExtruder.EndCap
    getEndCap()
    Returns the end cap value for the extrusion.
    PathExtruder.Joint
    getJoint()
    Returns the joint value for the extrusion.
    float
    getMitreLimit()
    Returns the mitre limit of the extrusion.
    Poly2
    getPolygon()
    Returns a polygon representing the path extrusion.
    Poly2
    getPolygon(Poly2 buffer)
    Stores the path extrusion in the given buffer.
    float
    getTolerance()
    Returns the error tolerance of the extrusion.
    void
    reset()
    Clears all computed data, but still maintains the settings.
    void
    set(float[] points, boolean closed)
    Sets the path for this extruder.
    void
    set(Path2 path)
    Sets the path for this extruder.
    void
    setEndCap(PathExtruder.EndCap endCap)
    Sets the end cap value for the extrusion.
    void
    setJoint(PathExtruder.Joint joint)
    Sets the joint value for the extrusion.
    void
    setMitreLimit(float limit)
    Sets the mitre limit of the extrusion.
    void
    setTolerance(float tolerance)
    Sets the error tolerance of the extrusion.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • PathExtruder

      public PathExtruder()
      Creates an extruder with no path data.

    • PathExtruder

      public PathExtruder(float[] points, boolean closed)
      Creates an extruder with the given path.

      The path data is copied. The extruder does not retain any references to the original data.

      Parameters:
      points - The path to extrude
      closed - Whether the path is closed

    • PathExtruder

      public PathExtruder(Path2 path)
      Creates an extruder with the given path.

      The path data is copied. The extruder does not retain any references to the original data.

      Parameters:
      path - The path to extrude

  • Method Details

    • set

      public void set(float[] points, boolean closed)
      Sets the path for this extruder.

      The path data is copied. The extruder does not retain any references to the original data. All points will be consider to be corner points.

      This method resets all interal data. You will need to reperform the calculation before accessing data.

      Parameters:
      points - The path to extruder
      closed - Whether the path is closed

    • set

      public void set(Path2 path)
      Sets the path for this extruder.

      The path data is copied. The extruder does not retain any references to the original data.

      This method resets all interal data. You will need to reperform the calculation before accessing data.

      Parameters:
      path - The path to extrude

    • reset

      public void reset()
      Clears all computed data, but still maintains the settings.

      This method preserves all initial vertex data, as well as the joint, cap, and precision settings.

    • clear

      public void clear()
      Clears all internal data, including initial vertex data.

      When this method is called, you will need to set a new vertices before calling calculate(float, float). However, the joint, cap, and precision settings are preserved.

    • calculate

      public void calculate(float lWidth, float rWidth)
      Performs an asymmetric extrusion of the current path data.

      An extrusion of a path is a polygon that follows the path but gives it width. Hence it takes a path and turns it into a solid shape. This is more complicated than simply triangulating the original path. The new polygon has more vertices, depending on the choice of joint (shape at the corners) and cap (shape at the end).

      This version of the method allows you to specify the left and right side widths independently. In particular, this allows us to define an "half extrusion" that starts from the center line.

      Parameters:
      lWidth - The width of the left side of the extrusion
      rWidth - The width of the right side of the extrusion

    • calculate

      public void calculate(float width)
      Performs a extrusion of the current path data.

      An extrusion of a path is a polygon that follows the path but gives it width. Hence it takes a path and turns it into a solid shape. This is more complicated than simply triangulating the original path. The new polygon has more vertices, depending on the choice of joint (shape at the corners) and cap (shape at the end).

      The stroke width is measured from the left side of the extrusion to the right side of the extrusion. So a stroke of width 20 is actually 10 pixels from the center on each side.

      Parameters:
      width - The stroke width of the extrusion

    • setJoint

      public void setJoint(PathExtruder.Joint joint)
      Sets the joint value for the extrusion.

      The joint type determines how the extrusion joins the extruded line segments together. See PathExtruder.Joint for the description of the types.

      Parameters:
      joint - The extrusion joint type

    • getJoint

      public PathExtruder.Joint getJoint()
      Returns the joint value for the extrusion.

      The joint type determines how the extrusion joins the extruded line segments together. See PathExtruder.Joint for the description of the types.

      Returns:
      the joint value for the extrusion.

    • setEndCap

      public void setEndCap(PathExtruder.EndCap endCap)
      Sets the end cap value for the extrusion.

      The end cap type determines how the extrusion draws the ends of the line segments at the start and end of the path. See PathExtruder.EndCap for the description of the types.

      Parameters:
      endCap - The extrusion end cap type

    • getEndCap

      public PathExtruder.EndCap getEndCap()
      Returns the end cap value for the extrusion.

      The end cap type determines how the extrusion draws the ends of the line segments at the start and end of the path. See PathExtruder.EndCap for the description of the types.

      Returns:
      the end cap value for the extrusion.

    • setTolerance

      public void setTolerance(float tolerance)
      Sets the error tolerance of the extrusion.

      This value is mostly used to determine the number of segments needed for a rounded joint or endCap. The default value is 0.25f.

      Parameters:
      tolerance - The error tolerance of the extrusion.

    • getTolerance

      public float getTolerance()
      Returns the error tolerance of the extrusion.

      This value is mostly used to determine the number of segments needed for a rounded joint or endcap. The default value is 0.25f.

      Returns:
      the error tolerance of the extrusion.

    • setMitreLimit

      public void setMitreLimit(float limit)
      Sets the mitre limit of the extrusion.

      The mitre limit sets how "pointy" a mitre joint is allowed to be before the algorithm switches it back to a bevel/square joint. Small angles can have very large mitre offsets that go way off-screen.

      To determine whether to switch a miter to a bevel, the algorithm will take the two vectors at this joint, normalize them, and then average them. It will multiple the magnitude of that vector by the mitre limit. If that value is less than 1.0, it will switch to a bevel. By default this value is 10.0.

      Parameters:
      limit - The mitre limit for joint calculations

    • getMitreLimit

      public float getMitreLimit()
      Returns the mitre limit of the extrusion.

      The mitre limit sets how "pointy" a mitre joint is allowed to be before the algorithm switches it back to a bevel/square joint. Small angles can have very large mitre offsets that go way off-screen.

      To determine whether to switch a miter to a bevel, the algorithm will take the two vectors at this joint, normalize them, and then average them. It will multiple the magnitude of that vector by the mitre limit. If that value is less than 1.0, it will switch to a bevel. By default this value is 10.0.

      Returns:
      the mitre limit for joint calculations

    • getPolygon

      public Poly2 getPolygon()
      Returns a polygon representing the path extrusion.

      The polygon contains the original vertices together with the new indices defining the wireframe path. The extruder does not maintain references to this polygon and it is safe to modify it.

      If the calculation is not yet performed, this method will return the empty polygon.

      Returns:
      a polygon representing the path extrusion.

    • getPolygon

      public Poly2 getPolygon(Poly2 buffer)
      Stores the path extrusion in the given buffer.

      This method will add both the original vertices, and the corresponding indices to the new buffer. If the buffer is not empty, the indices will be adjusted accordingly. You should clear the buffer first if you do not want to preserve the original data.

      If the calculation is not yet performed, this method will do nothing.

      Parameters:
      buffer - The buffer to store the extruded polygon
      Returns:
      a reference to the buffer for chaining.

    • getBorder

      public Path2[] getBorder()
      Returns a (closed) path representing the extrusion border(s)

      So long as the calculation is complete, the vector is guaranteed to contain at least one path. Counter-clockwise paths correspond to the exterior boundary of the stroke. Clockwise paths are potential holes in the extrusion. There is no guarantee on the order of the returned paths.

      If the calculation is not yet performed, this method will return the empty path.

      Returns:
      a (closed) path representing the extrusion border

    • getBorder

      public Path2[] getBorder(Path2[] buffer)
      Stores a (closed) path representing the extrusion border in the buffer

      So long as the calculation is complete, the vector is guaranteed to contain at least one path. Counter-clockwise paths correspond to the exterior boundary of the stroke. Clockwise paths are potential holes in the extrusion. There is no guarantee on the order of the returned paths.

      This method will attempt to store its results in the provided buffer, erasing the first one or two elements. If the buffer is not large enough, a new one will be created.

      If the calculation is not yet performed, this method will do nothing.

      Parameters:
      buffer - The buffer to store the path around the extrusion
      Returns:
      buffer with a (closed) path representing the extrusion border being added