Overhaul custom shapes for p5.js 2.0

[GregStanton]

Resolves

Resolves #6560 (main issue)
Resolves #6766 (main issue)
Resolves #3352 (resolved by main issues)
Resolves #906 (resolved by main issues)
Resolves #6555 (resolved by main issues)
Resolves #5722 (resolved by main issues)
Resolves #2274 (resolved by main issues)

Addresses

Addresses #6459 (facilitates addition of arcVertex())
Addresses #3651 (partially addressed?)
Addresses #3509 (makes shapeMode() possible in the future)
Addresses #5670 (may facilitate progress via a PointAtLengthGetter visitor class)
Addresses #6679 (adds new named defaults, including OPEN for contours and PATH for shapes)
Addresses #4630 (new Shape class may facilitate SVG import and export)
Addresses #4086 (see this comment for relationship to textToPoints())
Addresses #7026 (may help in relation to textToPoints(); anything else?)
Addresses #7016 (allows custom shapes to be constructed on base renderer)

Changes

Summary

This PR provides a new foundation for custom shapes in p5.js, an enhanced feature set and API, and streamlined shape rendering.

Foundation: Shape -> Contours -> Primitives -> Vertices

The foundation for all changes is a new Shape class, which consists of Contour objects. Contours may be thought of as general subshapes; they may be of any shape kind, including PATH, POINTS, LINES, TRIANGLES, etc.

Each contour is built from primitive objects, which are instances of classes such as BezierSegment and Triangle. Finally, each primitive consists of one or more Vertex instances. Vertex properties are generated dynamically, so a vertex may have just a position, or it may have other properties such as texture coordinates, a normal vector, a fill color, and a stroke color.

Features and API

Shapes allow mixing path segments of different kinds within a single path, as well as mixing contours of different kinds within a shape. (Although, support for mixing contours in WebGL may need to be added later.) Texture coordinates are supported by all vertex functions. Splines are now more flexible (with different end modes) and more intuitive (with interpolated endpoints by default). Users have access to these features through a revamped API for the vertex functions, with clear and consistent default values.

Processing, exporting, and rendering

Shapes may be processed or exported to other formats using visitor classes. For example, they may be converted to Path2D objects for 2D rendering, or other formats for 3D rendering.

Shapes can also be constructed and used independently of any renderer. For rendering, an abstract base renderer now handles all shape construction in one place, while concrete renderers customize shapes by selecting the vertex properties they support.

Itemized changes

The main changes are listed below.

• [non-breaking] Replaces Vertex submodule with Custom Shapes submodule (for clarity in the reference)
• [non-breaking] Adds custom-shape base classes (shapes, contours, shape primitives, and vertices)
• [non-breaking] Adds custom-shape visitor classes (for converting shape primitives to Path2D objects or vertices)
• [non-breaking] Refactors renderers (to construct Shape instances and to apply visitors for rendering)
• [non-breaking] Makes shape setters function jointly as getters (stroke() returns current stroke, for example)
• [breaking] Replaces curve() and curveTightness() with spline() and splineTightness()
• [breaking] Generalizes curveDetail() and removes bezierDetail() (replaces count with density, for custom shapes)
• [breaking] Removes beginGeometry()/endGeometry() in favor of buildGeometry()
• [breaking] Implements new vertex-function API
  • new defaults include PATH, OPEN, and SHOW for shapes, contours, and spline ends, respectively
  • new signatures include x, y, [u], [v] and x, y, z, [u], [v] for all vertex functions
  • bezierOrder(n) provides an extensible way to support multiple orders of Béziers
  • Breaking changes: removal of quadraticVertex(), new signature for bezierVertex(), replacement of curveVertex() with splineVertex(), new OPEN default for contours, and new SHOW default for spline ends.

Notes:

1. Some of the changes listed above are in progress.
2. This PR may also include an implementation of a point-at-length getter for path-segment primitives.
3. Removing beginGeometry()/endGeometry() eliminates an inconsistency with beginShape()/endShape(), reduces the size of the user-facing API, and prevents confusion (endGeometry() is effectively used as a constructor, in contrast with how objects are usually created in p5).

PR Checklist

Some areas are in progress during the draft phase of this PR.

• npm run lint passes
• Inline documentation is included / updated
• Unit tests are included / updated