Open GregStanton opened 7 months ago
Thanks for the writeup @GregStanton! I'm in favor of the consistency we'd get from an API like this, as well as the readability (any time a function has a bunch of positional arguments, I find myself having to write comments between arguments to remind myself which is which.)
For curveVertex texture coordinates, I think the same pattern we're suggesting for bezier vertices will also apply. When getting a position along a Catmull-Rom curve in between two control points, the interpolated position is a weighted sum of the curve's control points. I think we can do the same weighting for texture coordinates if we have one texture coordinate per control point, similar to position.
I do really like the overall simplicity and flexibility this can potentially give. One thing I would like to illustrate this proposal a bit more would be some more complete code examples, maybe even a before and after versions to make the use case clearer.
I'll probably share this with my colleagues teaching with p5.js to get their thoughts as well.
@limzykenneth Thanks! Code examples are a great idea. Here's a list of examples that illustrates some key differences:
Current syntax:
beginShape();
vertex(x0, y0, z0);
bezierVertex(x1, y1, z1, x2, y2, z2, x3, y3, z3);
endShape();
beginShape()
curveVertex(x0, y0, z0);
curveVertex(x1, y1, z1);
curveVertex(x2, y2, z2);
curveVertex(x3, y3, z3);
endShape();
Proposed Syntax:
beginShape();
bezierVertex(x0, y0, z0);
bezierVertex(x1, y1, z1);
bezierVertex(x2, y2, z2);
bezierVertex(x3, y3, z3);
endShape();
beginShape();
curveVertex(x0, y0, z0);
curveVertex(x1, y1, z1);
curveVertex(x2, y2, z2);
curveVertex(x3, y3, z3);
endShape();
Current syntax (the Bézier case isn't actually supported, but a user might expect this to work):
beginShape();
vertex(x0, y0, z0, u0, v0);
vertex(x1, y1, z1, u1, v1);
vertex(x2, y2, z2, u2, v2);
vertex(x3, y3, z3, u3, v3);
endShape();
beginShape();
vertex(x0, y0, z0, u0, v0);
bezierVertex(x1, y1, z1, u1, v1, x2, y2, z2, u2, v2, x3, y3, z3, u3, v3);
quadraticVertex(x4, y4, z4, u4, v4, x1, y1, z1, u1, v1);
endShape();
Proposed syntax (contours are used to specify separate pieces of different orders):
beginShape();
vertex(x0, y0, z0, u0, v0);
vertex(x1, y1, z1, u1, v1);
vertex(x2, y2, z2, u2, v2);
vertex(x3, y3, z3, u3, v3);
endShape();
beginShape();
beginContour();
bezierVertex(x0, y0, z0, u0, v0);
bezierVertex(x1, y1, z1, u1, v1);
bezierVertex(x2, y2, z2, u2, v2);
bezierVertex(x3, y3, z3, u3, v3);
endContour();
beginContour();
bezierVertex(x4, y4, z4, u4, v4);
bezierVertex( x1, y1, z1, u1, v1);
endContour();
endShape()
Current syntax (the first one will cause an error because it's not supported, due to an inconsistency):
quadratic(x0, y0, x1, y1, x2, y2);
bezier(x0, y0, x1, y1, x2, y2, x3, y3);
Proposed syntax:
bezier(x0, y0, x1, y1, x2, y2);
bezier(x0, y0, x1, y1, x2, y2, x3, y3);
Current syntax (this will produce an error because higher-order Bézier curves aren't currently supported):
beginShape();
vertex(x0, y0);
bezierVertex(x1, y1, x2, y2, x3, y3, x4, y4);
endShape();
beginShape();
curveVertex(x0, y0);
curveVertex(x1, y1);
curveVertex(x2, y2);
curveVertex(x3, y3);
curveVertex(x4, y4)
endShape();
Proposed syntax (this assumes we want to support higher-order Bézier curves):
beginShape();
bezierVertex(x0, y0);
bezierVertex(x1, y1);
bezierVertex(x2, y2);
bezierVertex(x3, y3);
bezierVertex(x4, y4);
endShape();
beginShape();
curveVertex(x0, y0);
curveVertex(x1, y1);
curveVertex(x2, y2);
curveVertex(x3, y3);
curveVertex(x4, y4);
endShape();
Current syntax (this is how a user might try to create a Bézier triangle, but that's not currently supported):
beginShape(TRIANGLES);
vertex(x0, y0, z0);
quadraticVertex(x1, y1, z1, x2, y2, z2);
quadraticVertex(x3, y3, z3, x4, y4, z4);
vertex(x5, y5, z5);
endShape();
Proposed syntax:
beginShape(TRIANGLES);
bezierVertex(x0, y0, z0);
bezierVertex(x1, y1, z1);
bezierVertex(x2, y2, z2);
bezierVertex(x3, y3, z3);
bezierVertex(x4, y4, z4);
bezierVertex(x5, y5, z5);
endShape();
One issue with having a single bezierVertex()
function (instead of separate functions for quadratic and cubic cases), is that we need some other way to infer the order when a single shape is made out of multiple Bézier curves or surfaces. See Example 2. (A similar situation arises with Bézier surfaces. For example, the case of three cubic Bézier triangles and the case of five quadratic Bézier triangles each require a total of thirty vertices; so, we can no longer determine the order of the surface based on the number of function calls.) One possible solution, based on contours, is indicated in Example 2.
Currently, composite shapes aren't supported, but #6560 would address this, and it provides more examples of that type in the current syntax.
I want to also invite @peilingjiang who created the p5.bezier addon library to have a look at this. Seeing that your library also deals with Bezier curves and also support higher order Bezier curves, it would be great to hear your thoughts, we can even look at the implementation you have in p5.bezier as a starting point for this too.
Thanks for the invite! Looking at the example code comparisons, I think this would be a very nice update, syntax-wise (I don't know how differently the updated functions will be implemented, so I'll only share some thoughts on the proposed syntax)! The vertex-related syntax would be unified, and having consistent, separate functions with a manageable number of arguments, instead of a crazy list of 9 or 15 arguments, would greatly improve the code readability.
For the implementation, I hope my implementation for the higher-order Bézier curves would be helpful to serve as a starting point for the new native support.
Moreover, I wonder if you would consider having an array of arrays of vertices, e.g.,
beginShape();
bezierVertices([
[x0, y0, z0, u0, v0],
[x1, y1, z1, u1, v1],
[x2, y2, z2, u2, v2],
[x3, y3, z3, u3, v3]
])
endShape();
I did something similar for the addon for the usability of the API, as managing items in an array (e.g., when adding or removing vertices) would be easier than modifying separate function calls. Moreover, the users may already maintain the positions somewhere else using nested arrays. This would be a further departure from the native Canvas API, but that might not be a bad thing - we could keep the old APIs for a few more minor version updates, mark them as deprecated, and introduce new ones like vertices
and bezierVertices
.
Thanks for your feedback @peilingjiang! Your library looks really cool, by the way. I think it'd be great to flesh out the pros and cons of your API idea, for the sake of discussion. I've already written up a partial list, but that gave me a new idea that I want to think about a bit more. I'll share what I have as soon as I'm able to think it over a bit more.
Okay, @peilingjiang! I have some initial feedback to share regarding the API you proposed.
The bezierVertices()
API (as opposed to the bezierVertex()
API) has some nice benefits. Here are a few of them.
curveVertex()
. Roughly, the way it works is that each vertex function adds its arguments to a primitive shape object. Since we're going to support composite shapes made of multiple types of primitives, curveVertex()
will check to see if the current primitive consists of curve vertices. If so, it will add its data to that segment, and if not, it will start a new primitive shape and add its data to that. With your API, we shouldn't need to check the type of the current segment. kinds
in a more extensible way, we end up creating a new curve primitive before checking the type of the current primitive. If the current primitive is already made of curve vertices, the new curve primitive's data is added to that, and then the containing object will be discarded, i.e. the memory should be reclaimed. So we sometimes have a very temporary object, which should be easier to avoid with your API.beginContour()
/endContour()
is a pretty simple solution (for a piece with control points A, B, C, and D, the user would also have to make sure the next piece starts with D, since using contours means it's no longer implied that pieces are glued together; but that seems like a minor issue).The bezierVertices()
API also has some potential cons.
WEBGL
renderer, it's possible to specify color (stroke or fill) for each vertex. Here's an example sketch. Similarly, the user can specify a normal vector for each vertex with normal()
. It's not immediately obvious how to achieve these kinds of features in a simple way with bezierVertices()
. (Thanks to @davepagurek for raising this point in conversation.)arcVertex()
, which I proposed previously in #6459; arcVertex()
is a crucial feature, for reasons cited in that issue. Fortunately, this discussion gave me an idea for a new arcVertex()
API that would eliminate this inconsistency; we're in the process of exploring its viability.Edit: Added first point under cons, about features of the WEBGL
renderer.
Just noticed a small thing that might need some clarification, and that's how to distinguish multiple segments of bezier curves.
In current p5, let's say I want to draw a square with two rounded corners, plus a cutout contour:
```js beginShape() vertex(20, 20) vertex(100, 20) quadraticVertex(180, 20, 180, 100) quadraticVertex(180, 180, 100, 180) vertex(20, 180) beginContour() vertex(40, 40) vertex(40, 100) vertex(100, 100) vertex(100, 40) endContour() endShape(CLOSE) ``` |
|
There are a few things going on here:
I think based on the proposal currently, the code would look like this:
beginShape()
vertex(20, 20)
vertex(100, 20)
// top right corner
beginContour()
bezierVertex(100, 20)
bezierVertex(180, 20)
bezierVertex(180, 100)
endContour()
// bottom right corner
beginContour()
bezierVertex(180, 100)
bezierVertex(180, 180)
bezierVertex(100, 180)
endContour()
vertex(20, 180)
// The inner contour
beginContour()
vertex(40, 40)
vertex(40, 100)
vertex(100, 100)
vertex(100, 40)
endContour(CLOSE)
endShape(CLOSE)
moveTo
in native canvas. I think these two uses are different, as fill winding order needs composite paths to still be part of one contour in order to calculate the winding order of the whole path correctly.
begin/endSegment
and leave begin/endContour
as is?I think it might solve some of those problems if you still have separate methods for separate orders as before, e.g. bezierVertex
and quadraticVertex
(and adding new ones for higher orders), but split each control point into multiple function calls.
So this: | ...becomes this: |
```js beginShape() vertex(20, 20) vertex(100, 20) quadraticVertex(180, 20, 180, 100) quadraticVertex(180, 180, 100, 180) vertex(20, 180) beginContour() vertex(40, 40) vertex(40, 100) vertex(100, 100) vertex(100, 40) endContour() endShape(CLOSE) ``` | ```js beginShape() vertex(20, 20) vertex(100, 20) quadraticVertex(180, 20) quadraticVertex(180, 100) quadraticVertex(180, 180) quadraticVertex(100, 180) vertex(20, 180) beginContour() vertex(40, 40) vertex(40, 100) vertex(100, 100) vertex(100, 40) endContour(CLOSE) endShape(CLOSE) ``` |
Now:
quadraticVertex
calls and cubic segments will always need three bezierVertex
calls, so you can just continue to add more and p5 will know where each one endsLike in your initial proposal:
fill()
or normal()
between each control point if you want to change those per control point instead of per segmentIn current p5, curveVertex
is the odd one out when it comes to picking up where the last segment left off, but that's mostly because it interprets the whole shape as curve vertices whenever you use a single curve vertex. Here are some thoughts about how to handle them now.
I think it makes sense for curve vertices to connect to the last point if it exists to add API consistency. I imagine Catmull-Rom splines like being a set of points, where we determine the tangents by looking at line between the previous and text points:
I'm imagining that if you put a Catmull-Rom curve in the middle of some other curves, it would connect thesecond curveVertex
(which is the first that gets drawn) to the previous segment, and connect the second-last curveVertex
to the next segment. e.g.:
Thanks so much @davepagurek! This is a great discussion.
I'm glad you raised the issue about using beginContour()
/endContour()
for two different purposes. This leads us to a possible improvement: how about having beginPrimitive()
/endPrimitive()
(instead of beginSegment()
/endSegment()
) and beginContour()
/endContour()
for the two purposes? The "Primitive" in the name would coincide with our current refactoring plan, which handles not just segments but other types of shape kinds as well.
Having beginPrimitive()
/endPrimitive()
in addition to beginContour()/endContour()
would have several benefits, including improvements not directly related to the problem you identified. I think that's a sign of a good design. Here's a list of advantages:
TRIANGLES
shape kind. Right now, we may have fifteen vertex()
calls in a row, and it's up to the person reading the code to mentally separate vertex()
calls into groups of three, and then determine that the code should produce five triangles based on that. If users wrap every three vertices in beginPrimitive()
/endPrimitive()
, it's easier to determine that the code should produce five triangles. (The code would be a bit longer, but the added length seems worthwhile.)beginPrimitive()
won't entail a moveTo()
operation for segments like beginContour()
does.beginPrimitive()
/endPrimitive()
seems to provide most of the benefits of bezierVertices()
, without the downsides we identified.
beginPrimitive()
may just set a flag to indicate that a new primitive is to be started, and it'd no longer be necessary to check the type of the previous primitive.)quadraticVertex()
for disambiguation would reintroduce those problems or replace them with new problems.Yep! The current refactoring plan handles curveVertex()
in the way that you described. Each type of segment will be represented internally by its own class (LineSegment
, BezierSegment
, etc.) These classes implement the Segment
interface, which has the methods getStartVertex()
and getEndVertex()
. These can work differently depending on the type of segment. For example, the getEndVertex()
method of a CurveSegment
object will get its second-to-last vertex. So, "end vertex" doesn't refer to the last vertex specified, since that may be a control point that's not on the segment itself; instead, it refers to the vertex that's on the actual end of the segment. If we can come up with a clearer name, that might clear up any confusion. Maybe getStartPoint()
and getEndPoint()
?
Note: These are initial thoughts. It will be good to confirm the details when time permits.
I think beginPrimitive()/endPrimitive()
addresses the conflicts with beginContour
, so that makes sense, thanks! Engineering-wise, I think this all would be safe to implement.
I think as a matter of opinion, I'm still unsure that the extra code required to surround each segment by begin/endPrimitive
is worth it? It seems like it has the following pros:
quadraticVertex
and bezierVertex
The con for me is really just:
At least in my own experience, I've rarely felt the need to go higher than a cubic Bezier, and SVG/CanvasRenderingContext2D APIs don't natively support them either. I'd still love to support them, but I'm personally OK going with a more complex API for those since I see them as a very special case. Meanwhile, most shapes I'd want to draw (imagine drawing text glyphs as a motivating example) are composed of connected lines and curves, often with many connected cubic segments. Since a single text glyph can have upwards of 20 segments in it, and each segment would now need a duplicate vertex to remain connected, this adds a lot of overhead, which gives me pause.
As an alternative, I think if we break each control point into their own call but don't try to support multi-order bezier and don't try to surround segments with other functions, we'd still check the other boxes we wanted.
That's just an opinion based on my own experience though! I want to hear if other people's experience is similar to that too.
As a final aside, I think if we keep separate methods for the different bezier orders, maybe it's worth aliasing bezierVertex
to cubicVertex
and referring to it as the latter in our docs.
Thanks @davepagurek! I'll reply to your points about using beginPrimitve()
/endPrimitive()
to distinguish primitive shapes, as well as your ideas about naming.
beginPrimitive()
/endPrimitive()
With beginPrimitve()
/endPrimitive()
, I don't think we need to duplicate vertices for continuity. That's what I meant by the following:
This allows us to support implicit start vertices for segments in composite paths, since beginPrimitive() won't entail a moveTo() operation for segments like beginContour() does.
If I'm thinking about that incorrectly, please let me know!
For me, part of the problem right now is that Bézier curves are already a special case that needs to be thought about differently. If we support higher-order Bézier curves and distinguish individual segments with beginPrimitive()
/endPrimitive()
, then all segment primitives will work in a consistent way (I'll paraphrase a comment I made on #6459):
With the proposed API, none of the vertex functions has an upper bound on the number of vertices that may be specified:
vertex()
works with any number of vertices greater than onebezierVertex()
works with any number of vertices greater than twocurveVertex()
works with any number of vertices greater than threearcVertex()
works with any number of vertices greater than four
I'm glad you raised the issue of naming.
quadraticVertex()
I think quadraticVertex()
is a problematic name by itself (see Problem 7 in the body of this issue). Regarding the name bezierVertex()
, cubicVertex()
is better in some ways, but it introduces other problems; for example, Catmull-Rom splines are also cubic, and there'd be no obvious indication in the API whether we're using Bézier curves or something else. This discussion also raises an issue with curveVertex()
that's been in the back of my mind...
curveVertex()
The name "curve" kind of pollutes the namespace since there are a lot of possible curves, and now we can't use "curve" to refer to anything but Catmull-Rom splines, unless we want to be inconsistent. We can already see this inconsistency in the p5.js reference, where "Curve" is used as a generic section heading for functions that include "curve()" and also "bezier()". Using "curve" to refer to Catmull-Rom splines is also inconsistent with the native canvas API's use of the term "curve" (it uses that term in bezierCurveTo()
, for example).
In other words, "curve" is ambiguous since it doesn't specify the type of curve. The name catmullRomVertex()
is a bit long and maybe hard to spell, so maybe hermiteVertex()
? This would be pretty specific, it'd be consistent with the name bezierVertex()
in that both are named after people, and it'd allow some flexibility (e.g. Cardinal splines, Catmull-Rom splines, and Kochanek–Bartels splines are Hermite splines with different choices of tangents). I feel like it might take some getting used to, and naming ideas after people can lead to other problems (but for better or worse, this usage is pretty well established and won't be easy to change).
Another option is something like splineVertex()
, which is not ideal since Béziers are also sometimes referred to as splines, but it's at least more precise than curveVertex()
.
Just to be clear, I haven't fully thought through beginPrimitive()
/endPrimitive()
yet, and I'm making these points for the sake of discussion. So it'd be great if anyone wants to add to their feedback! Fleshing out a mock documentation page could be helpful too; that would force us to think through the different uses and how we'd explain them.
This allows us to support implicit start vertices for segments in composite paths, since beginPrimitive() won't entail a moveTo() operation for segments like beginContour() does.
I think the issue I was thinking of is that, if there isn't an implicit moveTo
, then a cubic vertex segment only needs 3 control points (the fourth is borrowed from the previous curve.) In example 1 above though, we have this:
Current API | Proposed API |
```js beginShape(); vertex(x0, y0, z0); bezierVertex(x1, y1, z1, x2, y2, z2, x3, y3, z3); endShape(); ``` | ```js beginShape(); bezierVertex(x0, y0, z0); bezierVertex(x1, y1, z1); bezierVertex(x2, y2, z2); bezierVertex(x3, y3, z3); endShape(); ``` |
Here we've got all four in the segment. I guess the point I'm unclear on is whether or not that's a special case for just the first segment? e.g. would the following also be valid?
beginShape();
vertex(x0, y0, z0);
beginPrimitive();
bezierVertex(x1, y1, z1);
bezierVertex(x2, y2, z2);
bezierVertex(x3, y3, z3);
endPrimitive();
endShape();
If it is, then does that mean that within the first primitive, bezier segments will always have one fewer point than in the later ones?
For me, part of the problem right now is that Bézier curves are already a special case that needs to be thought about differently.
For context, what is the special case you're referring to here?
Thanks for bringing up these points @davepagurek! This is all helpful for filling in the details.
Yeah, I probably could've worded that more clearly. What I meant was that vertex()
can be called an unbounded number of times to create a polyline, and curveVertex()
can be called an unbounded number of times to create a Catmull-Rom spline. With the latest idea in #6459, we can even call arcVertex()
an unbounded number of times to create an elliptical arc that fits the data. If we continue to use quadraticVertex()
for quadratic Béziers and bezierVertex()
for cubic Béziers, then unlike all the other vertex functions, these may only be called a fixed number of times.
So, I really meant that quadraticVertex()
/bezierVertex()
represent a distinct case. If we remove quadraticVertex()
and use bezierVertex()
to specify Bézier curves of any order, then Bézier curves will no longer be a distinct case. They'll work the same as all the other kinds of curves. That's a simplification regardless of whether people end up using higher-order Bézier curves, since we won't have to remind them to never use quadraticVertex()
more than three times and to never use bezierVertex()
more than four times.
beginPrimitive()
/endPrimitive()
?For the very first primitive, we might want to make beginPrimitive()
/endPrimitive()
optional, so that the following two code snippets do the same thing:
With beginPrimitive()
/endPrimitive()
:
beginShape();
beginPrimitive();
bezierVertex(x0, y0, z0);
bezierVertex(x1, y1, z1);
bezierVertex(x2, y2, z2);
bezierVertex(x3, y3, z3);
endPrimitive();
endShape();
Without beginPrimitive()
/endPrimitive()
:
beginShape();
bezierVertex(x0, y0, z0);
bezierVertex(x1, y1, z1);
bezierVertex(x2, y2, z2);
bezierVertex(x3, y3, z3);
endShape();
There are pros and cons to making these commands optional for the first primitive. If we always use beginPrimitive()
/endPrimitive()
, we'll increase consistency, but we'll also add an extra pair of commands that won't be entirely necessary in all cases. I guess I'd probably prefer to err on the side of consistency in the reference examples, but we could make it so that the code still works if the first primitive is specified without beginPrimitive()
/endPrimitive()
(then users who forget these commands won't have to do any debugging).
I think it makes sense for all of a primitive's vertices to always go inside beginPrimitive()
/ endPrimitive()
, including the first vertex. For example, we could make it so that a cubic Bézier segment can always be made with four vertices, each of which would be passed to bezierVertex()
:
beginPrimitive();
bezierVertex(x0, y0, z0);
bezierVertex(x1, y1, z1);
bezierVertex(x2, y2, z2);
bezierVertex(x3, y3, z3);
endPrimitive();
However, if the first vertex duplicates the last vertex of a previous primitive, then we could allow the first vertex to be omitted.
I don't think we ever need to use vertex()
to specify a vertex in any kind of segment except a line segment (I guess using vertex()
to start off other kinds of segments is only necessary in the current API because quadraticVertex()
and bezierVertex()
aren't currently designed to accept a single vertex).
I haven't thought through the implementation yet, but I wanted to reply quickly to keep the conversation going. As a next step, one thing we might consider is replacing the segment primitives in our refactoring plan with classes for polylines, Béziers, Catmull-Rom splines, and elliptical arcs. Each of these could hold an unbounded number of vertices. For example, the polyline class would replace the line segment class. That way, we could specify a whole polyline between beginPrimitive()
/endPrimitive()
, and that would match the internal representation.
Thanks for explaining! I think my confusion about the special casing is because I saw a different pattern in vertex/quadraticVertex/bezierVertex: all can be used to chain multiple segments, but each segment has an increasing number of control points (1, 2, then 3) from the last point. In fact, vertex() can be seen as a linear bezier, which is just a line segment, needing no control point in the middle. In that sense, adding multiple vertices isn't different from cubic beziers, since each straight line is a segment, not the whole polyline.
(That's also why curveVertex felt like the odd one out to me, where all the points make up one segment. For what it's worth, the curveVertex workflow feels pretty separate from the rest, which are shared in other vector software. A possibly simplifying mental model would just be to treat curve vertices as a shortcut to bezier segments rather than a "real" primitive?)
One of the things that still feels inconsistent in the variable-order proposal is that multiple vertices adds more segments, but multiple of arc or bezier vertices increases the order of the same segment. To me it feels that to be consistent, more vertices in a row would do a line of beat fit through them rather than a polyline. I think the heart of what I'm suggesting is to always add more segments as the standard behavior.
The shift I was initially imagining was from grouping all control points of a segment extension into a single function call, to putting each control point into its own call., and the difference between segment extension types would be the interval at which a whole segment is complete. So vertex() calls, needing only one control point, add a new segment each time, quadratic points add a new segment every other point, cubic every three, and one could add quartic and quintic in the future that add a segment every four and five. (One could maybe add a generic version where you pass in the order into the first parameter.)
Of course, this is all from a frame of mind where chaining is key. I still think this in my own work this is the case that is most common, where paths are composed of many segments. I ideally want the freedom that vertex() has in your proposal, where you can keep chaining more of them without boilerplate, for bezier curves too, since I think in your proposal right now every cubic segment would need to be bounded by begin/endPrimitive. Do you think there's anything we can do in the API proposal to make that use case a bit easier?
Another thought: if we do go the route of having chains of vertices be all one segment like you're suggesting, maybe curve vertices don't have to be a separate thing, but just an interpolation strategy for those vertices?
So for an API, that would mean quadratic and cubic vertices continue to chain the same way normal vertices do, but you could surround vertices in begin/endSegment(interpolationStrategy)
where instead of chaining, we use something akin to basing the order off of the number of points like before?
Sorry if I'm derailing a bit haha, just wanted to share some thoughts that might combine both models!
This is getting very interesting @davepagurek! I'm going to think about this some more. As if we didn't already have enough to think about, here are some papers that your recent comments inspired me to discover:
I've only barely glanced through them, but the first of these seems to provide an interesting framework for a whole class of splines, which includes Bézier splines and elliptical splines (splines made from elliptical arcs) as special cases. They're distinguished by choosing different interpolation functions. The second article seems to develop an approach that's specific to splines made up of elliptical arcs.
I need to think through everything again in light of all this discussion, so I'm not sure if these will be relevant yet, but I figured I'd share them in case they inspire ideas from others.
Good morning again, just adding a summary comment about some of the discussion so far so it's easier to follow!
bezierVertex()
into its own call.curveVertex
also arguably works like this.)quadraticVertex
, bezierVertex
, and arguably vertex
currently work.)Potentially we can include both: the approximating/interpolating mode proposal would surround segments with begin/endPrimitive()
. This could potentially coexist with chaining API functions, which aren't surrounded, e.g.:
beginShape()
// Chaining
vertex(0, 0)
quadraticVertex(50, 0)
quadraticVertex(50, 50) // completes one quadratic segment
quadraticVertex(50, 100)
quadraticVertex(0, 100) // completes a second quadratic segment
// Aggregating
beginSegment(BEZIER)
vertex(-20, 80)
vertex(20, 50)
vertex(-20, 20)
vertex(0, 0)
endSegment() // completes a single quintic bezier segment
endShape()
Thanks so much for the summary @davepagurek! I'll add a few thoughts about the existing options and propose a new one.
One option is to keep the original proposal, with a few changes.
bezier()
to cubicBezier()
and create a new quadraticBezier()
function. (This solves Problem 6 of the proposal.)quadraticVertex()
and bezierVertex()
as quadraticBezierVertex()
and cubicBezierVertex()
, respectively. These names are longer, but the parameter lists are shorter, so it should be okay. (This solves Problem 7.)In this case, we would sacrifice extensibility (e.g. higher-order Bézier curves); in other words, we wouldn't try to solve Problem 8 of the original proposal.[^1] We’d also lose the simplicity of being able to call any vertex function an unlimited amount of times.
Here I'll add some issues to consider in relation to the idea you recently proposed.
beginSegment()
, we'll have beginTriangleFan()
, etc. Rather than expanding the size of the API significantly, one way to possibly address this is to replace beginSegment(interpolationStrategy)
with beginPrimitive(kind)
. Then BEZIER_SEGMENT
would be just one example of a shape kind. This isn't perfect, since it'd be nice if the primitive kinds would be the same as the shape kinds, but that'd require some extra complexity, e.g. beginPrimitive(vertexKind, shapeKind)
.vertex()
is just used for linear shapes in one API [^2], but it's used for other kinds of shapes in the other API.Below, I'll describe one approach that seems to do everything we want in a simple way. It's a variation of the API proposed by @peilingjiang. I'm not sure about it yet, but it seems really nice.
The idea is to have four vertex functions:
linearVertices()
for polylinesbezierVertices()
for Bézier curvescatmullRomVertices()
for Catmull-Rom splines [^3]arcVertices()
for elliptical arc splines [^4] As in the current version of p5.js, each function call creates a new segment (when the default shape kind is being used), and multiple calls will chain segments. There are two main differences from the current API:
p5.Vertex
class. Vertex objects would have properties for position, texture coordinates, color, and a normal vector. [^5] This would make it possible to support features like per-vertex coloring while retaining the benefits of @peilingjiang’s API. In particular, it makes code easier to read by explicitly grouping vertices into primitives, and it may allow for a simpler implementation that directly reflects the API.As an initial example, here's how we could create a cubic Bézier segment:
let v1 = createVertex(...);
let v2 = createVertex(...);
let v3 = createVertex(...);
let v4 = createVertex(...);
beginShape();
bezierVertices(v1, v2, v3, v4) //vertices could also be created inline, with one argument per line
endShape();
//ALTERNATIVE
let vertices = [
createVertex(...),
createVertex(...),
createVertex(...),
createVertex(...)
];
beginShape();
bezierVertices(...vertices); //could support array arguments if we want to avoid spread syntax
endShape();
This would be a slight departure from typical p5.js usage, which has users passing coordinates directly into functions, but it's similar to how we already allow users to pass a p5.Vector
object directly into point()
.
If we don't immediately see any major problems with this overall approach, I can work out more of the details (e.g. I can redo this list of examples in the new API).
[^1]: With this approach, it might still be possible to mostly solve Problem 9, e.g. by calling quadraticBezierVertex()
six times for a quadratic Bézier triangle and calling cubicBezierVertex(x, y, z)
ten times for a cubic Bézier triangle. Similarly, we could call quadraticBezierVertex()
nine times for a biquadratic patch and cubicBezierVertex()
sixteen times for a bicubic patch.
[^2]: Here, I'm ignoring the possibility of manually specifying normal vectors for vertices, since that's a less common use case.
[^3]: Although curveVertex()
is a friendly name, in that "curve" is a common word, it's overly generic and inconsistent with the other names, which are more specific. This can lead to confusion. For example, right now, there's a section of the reference called “Curves,” and underneath, it has both bezier()
and curve()
commands; so according to the reference, a bezier()
is a curve, but it's not a curve()
. So we may consider renaming curveVertex()
(or curveVertices()
) to something less generic, like hermiteVertex()
, catmullRomVertex()
, or even splineVertex()
. Although splineVertex()
is still too general (e.g. one can also make Bézier splines), it’s more precise than the current name. This note applies to all three APIs considered in this comment.
[^4]: The idea is that we can interpolate points with elliptical arcs instead of Bézier curves or something else. I cited a couple papers on this previously: here's one interesting paper that shows how to create both Bézier and elliptical splines in a common framework, and another paper that focuses specifically on "blended elliptic arc" splines. If we were to adopt an approach like this, we'd still need to consider how easy it'd be to create a single ellipse or elliptical arc. Also, this would probably mean that we would not try to support curve fitting (e.g. for fitting a single arc or line segment to a large number of vertices), as discussed in #6459, unless we provide a separate API for that.
[^5]: If this idea seems promising, we'll want to vet the idea of a p5.Vertex
class more carefully. One issue we've come across before is that we may end up with some null properties, which may be a sign that we need to split the class up. However, a single p5.Vertex
class would be consistent with p5's usual approach of providing a small interface to a large number of features (e.g. p5.Vector
combines 2D and 3D vectors).
Thanks @GregStanton! Here are a few thoughts on the different ideas you mentioned.
beginPrimitive
to handle all those cases seems good to me.curveVertex
and other vertex functions is pretty confusing to people currently, based on some Discord questions in the past.)createVertex
though: if it takes positional arguments (e.g. createVector(x, y, z, u, v)
) it becomes hard to supply just a color and not a texture coordinate, or something like that. We might need it to be createVector(x, y, z, options)
where options
can be { u: 0, v: 0 }
and only fill in the keys that are needed.@davepagurek I have some initial impressions but haven't had the opportunity to teach this part of API yet. I'll share some thoughts soon.
@tabreturn you know much more about teaching curves than I do. What do you think about the proposal?
I'll need to make some time to study this properly -- but it looks interesting!
The 2.0 advisory committee was looking at all the proposals, and the feedback on this one is that the most important goal here is to increase simplicity and predictability, and the larger departures from the existing API end up complicating things too much to be worth it. So I think to move forward with this one, the best approach would be to narrow the focus and pick out the bits that offer incremental improvements to just the current p5 shape functions.
In this case, I think that means going back to the chaining-only API described above. To summarize, from the current API:
fill()
, stroke()
, normal()
, etc to be changed per vertex by interleaving function calls
bezierControl
(as in control point) or bezierHandle
(as in handle, borrowed from the handles in vector editors)beginContour()
/endContour()
around the first path in a shape -- it just denotes a distinct, disconnected part of the shape. This just makes it align more with how native shape drawing works, and makes easier to handle sub-paths (e.g. when drawing a font from data) without special casing the first contour.This compromises the original proposal's side goal of allowing higher order Beziers and different interpolation schemes. I think if we want, we can extend the above to cover some of those other points by adding a curveMode()
call, which (1) can be used to specify the start of a new set of curveVertex
points if one wants to split a long chain into two, and (2) lets us add other interpolation modes one might use, e.g. BEZIER
to interpret the vertices as a single higher order Bezier.
@davepagurek Thanks so much for sharing the feedback!
After reading it, I had a new idea that I'm excited about. I think it's consistent with the feedback, in spirit: it preserves the simplicity and predictability of the original API proposal, with few changes to the current API. It also happens to be very extensible. Actually, it solves all ten of the original problems, and it addresses the main flaw in the original proposal.
I’d like to make more code examples to vet the idea further, but I’m hoping to get some initial feedback first. The API is indicated below, along with a code example, and some additional context.
// mode function (could default to n = 3, with native support for n = 2 and 3, at least)
bezierOrder(n)
// vertex functions (brackets indicate optional parameters)
vertex(x, y, [z], [u], [v])
arcVertex(x, y, [z], [u], [v])
bezierVertex(x, y, [z], [u], [v])
splineVertex(x, y, [z], [u], [v])
beginShape();
// two quadratic Bezier curves
// explicit starting vertex is required for first segment in a shape
bezierOrder(2);
bezierVertex(x0, y0);
bezierVertex(x1, y1);
bezierVertex(x2, y2);
bezierVertex(x3, y3);
bezierVertex(x4, y4);
// one cubic Bezier curve
// implicit starting vertex is at x4, y4
bezierOrder(3);
bezierVertex(x5, y5);
bezierVertex(x6, y6);
bezierVertex(x7, y7);
endShape();
This API
bezier()
with quadraticBezier()
and cubicBezier()
(Problem 6) [^1]quadraticVertex()
and bezierVertex()
(Problem 7), without longer function namesIt also solves an additional problem not identified in the original proposal's list of ten problems:
curveVertex()
uses a general term for a special shape. For example, in the p5 reference, “Curves” is used as a general section heading that includes Béziers, while curve()
specifically creates Catmull-Rom splines only. This may lead to confusion.The term "spline" is more specific, while also being general enough to allow other types of splines in the future, e.g. via a function such as splineType()
(either natively or via an add-on library). If we were to use a function name like curveType()
, the two uses of "curve" would make it harder to guess its purpose.
arcVertex()
I’ve added arcVertex()
to this version of the API, since it looks like we are going to add it. The syntax for arcVertex()
that’s indicated here is different from the syntax originally proposed in #6459, but this change was discussed in the comments on that issue. A benefit is that it would make arcVertex()
more consistent with the other vertex functions. Just as every four cubic Bézier vertices form a segment, every five arc vertices form a segment. However, we haven’t yet discussed the inclusion of texture coordinates in arcVertex()
.
If this idea looks good overall, we could...
arcVertex()
. (We could do that over in #6459.)[^1]: By making n = 3
the default order, bezier()
would already make Bézier curves of the default order. For non-default orders, users would still be able to use the more customizable beginShape()
/endShape()
and bezierVertex()
.
I'm a fan of that proposal!
In your example, do you think that you can start with a bezierVertex()
and then add two more to make a cubic bezier segment? Or would it instead be a little closer to the current API, where you start with a vertex()
and then add two bezierVertex()
es after that? I think I'm actually a bit more inclined to use the latter, because that means that a cubic bezier always involves adding two more calls to the last point to add a new segment, whereas it might be harder to determine where segments start/end if it can maybe also start with one.
I'm a fan of that proposal!
Yay! Also, you've identified the exact issue that's been on my mind. It seems to be the only remaining detail to sort out (famous last words haha). For anyone who is following along, I'll describe it below, and I'll discuss a few ways we might proceed.
In the version of the API under discussion, Bézier curves of the same order can require different numbers of function calls. For example, when a Bézier segment of order 2
(quadratic) is chained onto an existing segment, it requires two function calls, which is simple for users to remember; however, when it's the first segment in a shape, it requires three function calls.
This issue arises because a Bézier curve of order n
always requires n+1
vertices $V_0, V_1, ... , V_n$, but $V_0$ needs to be specified explicitly only when the curve is not chained onto a previous segment.
I'll describe the options presented so far, along with one new option. I'll also indicate costs and benefits of each option.
It'd be nice if a Bézier curve of order n
always required n
calls to bezierVertex()
, but the proposed API does have a kind of consistency: a new Bézier curve of order n
always requires n
new Bézier vertices to be added to an existing vertex.
Also, this pattern for reusing vertices is precisely consistent with existing vertex features (triangle fans, triangle strips, and quad strips use the same pattern). For example, when using the TRIANGLE_STRIP
shape kind with beginShape(), the first triangle requires three vertex calls, but thereafter, only one vertex call is required to add the next triangle, since the next triangle reuses two vertices from the previous triangle. This is the same idea as requiring three Bézier vertices for the first Bézier curve and requiring only two Bézier vertices for the next curve, since the next curve reuses a vertex from the first curve.
vertex()
for an explicit first vertexbeginShape();
// two quadratic Bezier curves
// explicit starting vertex is required for first segment in a shape
bezierOrder(2);
vertex(x0, y0);
bezierVertex(x1, y1);
bezierVertex(x2, y2);
bezierVertex(x3, y3);
bezierVertex(x4, y4);
// one cubic Bezier curve
// implicit starting vertex is at x4, y4
bezierOrder(3);
bezierVertex(x5, y5);
bezierVertex(x6, y6);
bezierVertex(x7, y7);
endShape();
It might be reasonable to use vertex()
to specify an explicit first vertex when an implicit one is not available, since that's how the existing p5 API works. My concern is that this introduces other inconsistencies:
vertex()
to start bezierVertex()
and arcVertex()
segments when an implicit vertex is not available, but it may be confusing for splineVertex()
to work this way. If splineVertex()
works differently, we'd reintroduce the inconsistency identified in Problem 3 of the original proposal.vertex()
makes shapes with straight sides, bezierVertex()
makes Béziers, etc. If we mix commands by using vertex()
to create part of a Bézier curve or arc, then the API will be less predictable (a newcomer seems less likely to predict that a Bézier curve needs to start with vertex()
, followed by bezierVertex()
, for example). vertex()
with multiple types of curves may complicate its documentation.bezierAnchor()
and arcAnchor()
beginShape();
// two quadratic Bezier curves
// explicit starting vertex is required for first segment in a shape
bezierOrder(2);
bezierAnchor(x0, y0);
bezierVertex(x1, y1);
bezierVertex(x2, y2);
bezierVertex(x3, y3);
bezierVertex(x4, y4);
// one cubic Bezier curve
// implicit starting vertex is at x4, y4
bezierOrder(3);
bezierVertex(x5, y5);
bezierVertex(x6, y6);
bezierVertex(x7, y7);
endShape();
The names bezierAnchor()
and arcAnchor()
don't have "vertex" in them, which is good, since these functions are different: they're only ever called to explicitly identify an anchor (i.e. a starting vertex $V_0$), at the beginning of a shape or contour.
Some benefits:
n
would always be created with n
calls to bezierVertex()
(as in Option 2).arcVertex()
(as in Option 2).Some disadvantages:
Thoughts?
Update: I refined the language and reasoning in Options 1, 2, and 3, e.g. by specifying additional disadvantages.
I'm still thinking about what other options there might be, but in the mean time, one comment on this bit:
We could potentially use vertex() to start bezierVertex() and arcVertex() segments when an implicit vertex is not available, but it may be confusing for splineVertex() to work this way. If splineVertex() works differently, we'd reintroduce the inconsistency identified in Problem 3 of the original proposal.
I'm imagining that each type of shape drawing function continues off of the last point, using its parameters to define how that continuation happens.
The native drawing context arcTo
also works kind of like this, where it adds a straight line segment to the start to make sure it's connected (blue is the initial "vertex", red is the control points of the arc):
```js ctx.moveTo(50, 50) // Analogous to `vertex` here ctx.arcTo(50, 150, 150, 150, 40); ctx.stroke() ``` | ![image](https://github.com/user-attachments/assets/751f7234-e2cf-442a-8348-499dd51d12e1) |
It's a little different for spline vertices because they could be used without continuing on from something else, which is the current inconsistency. Here's how that currently renders (the curve vertex points drawn in red for illustration):
```js beginShape() curveVertex(50, 50) curveVertex(50, 100) curveVertex(50, 150) curveVertex(100, 150) curveVertex(150, 150) endShape() ``` | ![image](https://github.com/user-attachments/assets/ec575c20-e0f2-49eb-bddf-bff5a3b4d5c8) |
If we were to make it consistent and require you to add a regular vertex
to the start, I'd expect it to still draw the same shape that we currently do, but also connect it to the last vertex somehow. Some options for that:
**Straight line:** still as confusing as current `curveVertex` because of the non-drawn control points, but at least predictable | ```js beginShape() vertex(100, 50) splineVertex(50, 50) splineVertex(50, 100) splineVertex(50, 150) splineVertex(100, 150) splineVertex(150, 150) endShape() ``` | ![image](https://github.com/user-attachments/assets/551d9cb9-3efa-45e8-9cdf-e51226712fdf) |
**Interpolated start point:** under the hood, it places two catmull-rom points at the start so that it smoothly goes from the previous point through to the rest of the curve. This makes the end behaviour a little inconsistent with the start, which leads me to the next row. | ```js beginShape() vertex(100, 50) splineVertex(50, 50) splineVertex(50, 100) splineVertex(50, 150) splineVertex(100, 150) splineVertex(150, 150) endShape() ``` | ![image](https://github.com/user-attachments/assets/0488e13c-36ef-4a66-939f-beae3591602d) |
**Interpolated start and end point:** under the hood, it places two catmull-rom points at the start and the end so that it goes through every point. This would make it consistent with how bezier points work and might be more obvious to newcomers, but also makes it hard to make something like a closed catmull-rom shape without a cusp. (That could maybe be fixed with a separate spline mode for smoothly closed shapes?) | ```js beginShape() vertex(100, 50) splineVertex(50, 50) splineVertex(50, 100) splineVertex(50, 150) splineVertex(100, 150) splineVertex(150, 150) endShape() ``` | ![image](https://github.com/user-attachments/assets/905ff86b-bd37-400e-8721-025469fa3c08) |
@davepagurek: Thanks so much for fleshing that out! It seems like you're moving toward making splines work more like polylines, which would be great for usability. It also makes sense, since polylines really are linear interpolating splines.
This got me digging into some different options, and it seems like we could maybe take this a step further. I need to develop this idea more, but I'll share what I'm thinking so far.
As an illustration of what I have in mind, you can try tinkering with this online demo. Try setting "Curve ends" to "Show," delete the default curve, and start adding control points one by one. You can leave the interpolation function on hybrid mode. The interface takes a little getting used to since points are added in random places, and you need to hover over the canvas to reveal the control points, but anyway...
The cool thing is that this demo allows the user to specify a smooth spline with just two vertices or more, and they're all rendered (as long as "Curve ends" is set to "Show"). With this kind of approach, making splines would be about as intuitive as making polylines! This would be simpler than the interpolated-start-and-end option in your last diagram, since that would still require the user to supply four vertices, and I think it'd be less clear why we need four vertices.
Note: This is a JavaScript and WebGL implementation of a new class of C^2 interpolating splines with some very nice properties; I'd be happy to share what I've learned about it (the researcher behind this is also an expert and seems available, e.g. via X). We may want to consider this new class for our implementation, but it may also be possible to come up with something similar without changing p5's implementation much.
While it may be nice to render all control vertices by default, the user would have less control if that were the only option. Perhaps we could support several modes, to be specified with a splineEnds()
function:
SHOW
: This could be the default and would work like your last case (interpolated start and end points).HIDE
: This would work more like curveVertex()
does in the current version of p5, when more control is needed.JOIN
: This would create a loop.These would correspond to "show," "hide," and "loop" in the online demo. However, there are some possible problems with this:
HIDE
mode is basically what p5 has now, so it may not work well with a vertex()
-first API (i.e. where every type of segment starts with a call to vertex()
). I do think it'd work if we keep the the latest proposal as is.I think that paper makes for a good curve mode, as maybe would Hobby curves. I think all of them have pros and cons, so having a curveMode
that we can add to makes sense to me.
This would be simpler than the interpolated-start-and-end option in your last diagram, since that would still require the user to supply four vertices
I'm imagining users won't need to specify four vertices to use Catmull-Rom if we want to modify it to always go through endpoints, since the duplication would happen under the hood. This would look something like this to end users (click to add points): https://editor.p5js.org/davepagurek/sketches/kVff25GyA In this way I think it would be interchangeable with the C^2 spline algorithm or Hobby curves.
I think the endpoint modes make sense! If using the HIDE
mode and you add more vertices before or after, we could connect them with straight line segments like in the example below to maintain the behaviour where every contour keeps making a connected line.
For joining: definitely a little weird that there's a separate CLOSE
, but possibly not the end of the world if we don't end up coming up with something better, as I think it still helps us cover a pretty common usage of smooth curves that is currently pretty hard to explain. I imagine if you have a closed loop in the middle of a path and you add more vertices afterwards, it would just continue off of the closed endpoint?
Also, here's a little implementation of how loop-closing Catmull-Rom with interpolated endpoints would look: https://editor.p5js.org/davepagurek/sketches/36Ro7HpR- Both this and Hobby curves are still cubic beziers under the hood, so it's maybe helpful for implementation that these strategies could both be implemented as translations or generators for a bezier path. (Edit for a little more context: other interpolation methods that aren't translatable to cubic bezier are still doable, it maybe would maybe just require us to convert it to a polyline for 2D mode to render it there. We'd be doing that anyway for WebGL mode so that's not a huge downside.)
Anyway before getting too much more in the weeds with curveVertex
options, a next step here might be to try to summarize the updated proposal and get some feedback on that again?
Thanks @davepagurek!
I went ahead and incorporated all the important updates into the original proposal. I included a section at the end to indicate which updates were made. I agree that gathering more feedback would be a good next step!
Also, your diagrams and sketches are all really helpful. I think that makes sense about Catmull-Rom not requiring four vertices if we're interpolating the control points at the beginning and end; thanks for the clarification. Your comments did give me some extra ideas about splines, which I've shared below.
Also, especially now that I've summarized the latest proposal, I have a couple extra points on the overall API that I'm curious to get your feedback on. I'll start with those, since they seem more fundamental.
splineVertex()
, bezierVertex()
, or arcVertex()
, rather than starting with vertex()
or anything else. This seems like an important point, which @tfadali pointed out to me in a real-time discussion (he's interested in this work, so I've been getting him up to speed).vertex()
already works the same way for making polylines: two vertices are required to make the first line segment, and thereafter, only one vertex is needed to generate a new segment.I'll reply to a few points about splines as well, in case it helps us make progress.
Yeah, I was thinking we could potentially have a splineType()
or something similar :) I'm holding off on the details for now in order to focus on splineEnds()
(or whatever we call it).
I wanted to reply quickly, so hopefully my reasoning makes sense in this section. If I'm thinking incorrectly, please let me know!
vertex()
In the version of HIDE
mode you mentioned, how would you create the curve in the picture below with no blue vertex (and no line segment connecting to the blue vertex)?
In the vertex()
-first approach, I'm imagining this code:
beginShape()
vertex(50, 50)
splineVertex(50, 100)
splineVertex(50, 150)
splineVertex(100, 150)
splineVertex(150, 150)
endShape()
It feels strange for vertex(50,50)
to create a non-interpolated control point at the start of a shape, even in HIDE
mode, since HIDE
mode applies to the spline, whereas using vertex()
makes it feel like the starting point isn't a part of the spline. Also, vertices at the start of a shape would be interpolated in every other situation. The possible confusion seems to be compounded by specifying one non-interpolated control point with vertex()
and the other with splineVertex()
.
This kind of issue is another reason that I seem to be leaning toward the no-change option (i.e. leaving the usage proposed in the updated proposal as is, rather than using vertex()
to start shapes).
Based on the latest approach you shared, it seems like we'd get the following output in the two modes.
SHOW |
HIDE |
---|---|
But, in SHOW
mode, it seems like we'd want the following instead:
P.S. It seems like the JOIN
case will take some more time to think through. I'm looking forward to working on that when I get a chance.
I'm ok with the idea that some things don't need to always start with a vertex, like the strip modes, and also splines. I think the consistent rule I'm imagining is that each new segment is responsible for transitioning from the last drawn point (not control point), if it exists, and that still holds for splines if they don't start with a vertex
(I'll show examples in the next section.)
I think my concern for bezier segments is that it's pretty rare to just have one Bezier segment compared to a chain of many of them. In that case, the concern that it's hard to tell segments apart in the code becomes the primary issue. I worry that if there isn't consistency (n calls always adds a new segment) then splitting a segment into multiple control points becomes too confusing, and that's the primary change that I personally am hoping to get out of the refactor. Forcing it to start with a vertex still keeps that rule above consistent: the difference between it and a spline is that splines can support arbitrarily many points in them, whereas non-splines always have a fixed amount (so I'd imagine arcVertex
works the same, and would also need to start with a vertex
.)
Slight aside, but I think spline ends only apply to some splines, like Catmull-Rom or something like B splines, so if we do add something like C^2 interpolating curves or Hobby curves, the HIDE
mode may just not apply to them. That's probably fine, curveTightness
would maybe not apply to everything either. I also wonder if renaming SHOW
to TOUCH
or INTERPOLATE
or some synonym might make sense (especially if we make that the default so you don't have to actually type it most of the time) to make it clear it changes the curve? Maybe INCLUDE
?
Anyway here's how I was imagining the end modes would work, keeping consistent that rule above:
```js beginShape() splineEnds(HIDE) // With no surrounding vertices splineVertex(50, 50) splineVertex(50, 100) splineVertex(50, 150) splineVertex(100, 150) splineVertex(150, 150) endShape() ``` | ![image](https://github.com/user-attachments/assets/e72cebb2-f3ff-4300-bfe1-c9c9298295ee) |
```js beginShape() splineEnds(HIDE) // With starting vertex vertex(100, 50) splineVertex(50, 50) splineVertex(50, 100) splineVertex(50, 150) splineVertex(100, 150) splineVertex(150, 150) // ...and ending vertex vertex(150, 100) endShape() ``` | ![image](https://github.com/user-attachments/assets/233c5a35-b84d-4a8d-bc08-7dc35a0799b7) |
```js beginShape() splineEnds(SHOW) // With no surrounding vertices splineVertex(50, 50) splineVertex(50, 100) splineVertex(50, 150) splineVertex(100, 150) splineVertex(150, 150) endShape() ``` | ![image](https://github.com/user-attachments/assets/362a20b2-7cf9-4bed-99e9-3cb10c514edd) |
```js beginShape() splineEnds(SHOW) // With starting vertex, the spline is responsible // for a smooth transition from there into the spline vertex(100, 50) splineVertex(50, 50) splineVertex(50, 100) splineVertex(50, 150) splineVertex(100, 150) splineVertex(150, 150) // ...but the vertex call is responsible for transitioning // out of the spline, so it's not smooth vertex(150, 100) endShape() ``` | ![image](https://github.com/user-attachments/assets/d5397c1c-4cfe-4bf4-bfa4-777551f75ae7) |
```js beginShape() splineEnds(SHOW) // With starting vertex vertex(100, 50) splineVertex(50, 50) splineVertex(50, 100) splineVertex(50, 150) splineVertex(100, 150) splineVertex(150, 150) // Bringing the last vertex "into" the spline ensures a smooth transition: splineVertex(150, 100) endShape() ``` | ![image](https://github.com/user-attachments/assets/934bdb9a-d9c6-4c3a-9fbc-3cc7f07d00f2) |
Thanks for all the examples @davepagurek!
In my last reply, I think I could've been clearer when I tried to answer your original question:
[To start a shape with a quadratic Bézier], do you think that you can start with a bezierVertex() and then add two more...? Or would it instead be a little closer to the current API, where you start with a vertex() and then add two bezierVertex()es after that? I think I'm actually a bit more inclined to use the latter, because that means that a cubic bezier always involves adding two more calls to the last point to add a new segment, whereas it might be harder to determine where segments start/end if it can maybe also start with one.
I'm totally empathetic to your position! I originally had the same concern. But, based on all the considerations so far, I'm actually proposing the former option... For the record, I'll try to clarify my current reasoning with an example. [^1]
Quad strip (current usage) | Bezier curves (proposed usage) |
---|---|
|
|
```javascript beginShape(QUAD_STRIP); // first quad // four vertices required vertex(30, 20); vertex(30, 75); vertex(50, 20); vertex(50, 75); // one more quad // two vertices required (two reused) vertex(65, 20); vertex(65, 75); // one more quad // two vertices required (two reused) vertex(85, 20); vertex(85, 75); endShape(); ``` | ```javascript beginShape(); // first quadratic Bezier curve // three vertices required bezierOrder(2); bezierVertex(5, 12); bezierVertex(41, 12); bezierVertex(23, 30); // one more quadratic Bezier curve // two vertices required (one reused) bezierVertex(5, 48); bezierVertex(41, 48); // one more quadratic Bezier curve // two vertices required (one reused) bezierVertex(182, 54); bezierVertex(41, 57); endShape(); ``` |
With strips and fans, we've already accepted that the first piece of a shape will require more vertices than the remaining pieces. If we can accept that for strips and fans, then I think we could accept it for curves. This has several benefits:
arcVertex()
, rather than vertex()
. Same for other curve types.bezierVertex()
, arcs using only arcVertex()
, etc.We do lose the simplicity of always calling bezierVertex()
exactly n
times to create a Bézier curve of order n
. However, there is still a kind of consistency: a new Bézier curve of order n
always requires n
new Bézier vertices to be added to an existing vertex. So on the whole, the current API seems to be a net gain for simplicity and predictability.
I was actually thinking about whether the end modes would only apply to some types of splines. Thanks for putting that on record. I have an initial idea of how we could handle that, but it's not ideal. I was thinking we could hash that out once the basics are in place.
I do think end modes would apply to the $C^2$ interpolating splines, fortunately. The "Show" and "Hide" modes in the online demo of those splines were actually my inspiration for suggesting different end modes. I still need to look more closely at Hobby curves.
For the rest of the issues around splines (names for the modes, etc.), maybe it'd make sense to set up one or more video calls at some point? In order to keep my GitHub replies from being super verbose, I've ended up omitting ideas or not communicating them clearly enough. Also, this discussion is getting long :) I usually prefer total transparency for anyone following along, but it might actually be easier for everyone if we just post summaries of real-time discussions?
[^1]: In the Bézier example, control points are rendered as a visual aid, but the code for that is not shown. [^2]: As we've been discussing, the spline case is special and may support more advanced variations, but it's possible for this exact pattern to hold in the default case (e.g. if the default spline type is Catmull-Rom, with interpolated start and end points).
Increasing access
Implementing this proposal would
As a result, p5.js would be more accessible to beginners, while offering others access to a wider feature set.
Which types of changes would be made?
Most appropriate sub-area of p5.js?
What's the problem?
Short version: The current API for vertex functions contains complexities, inconsistencies, and hard-to-extend features.
Long version: Eleven distinct problems arise from the current API for vertex functions. Below, each problem is listed and tagged with a problem type. (In case we want to modify the proposed solution, we can check the new version against this list.)
vertex()
but not toquadraticVertex()
,curveVertex()
, orbezierVertex()
, as noted in #5722. Under the current API, specifying texture coordinates would require up to fifteen parameters in a single function call, with the following syntax:bezierVertex(x2, y2, z2, u2, v2, x3, y3, z3, u3, v3, x4, y4, z4, u4, v4)
. [Inconsistency/Inflexibility]quadraticVertex()
andbezierVertex()
really do start withx2, y2
/x2, y2, z2
. That's because the first set of parametersx1, y1
/x1, y1, z1
must be specified separately, and we need a way to distinguish the second, third, and fourth points since they're grouped together in the same function call. [Complexity]x1, y1
/x1, y1, z1
gets passed tovertex()
. But that's just for Bézier curves. If we want to make a Catmull-Rom spline, the first point and all successive points get specified directly tocurveVertex()
. In other words, the current API allows the user to callvertex()
to start and continue a polyline, and to callcurveVertex()
to start and continue a Catmull-Rom spline; however, to start a shape with a quadratic or cubic Bézier curve, the user needs to mix commands. [Inconsistency]bezierVertex()
is named after a single vertex, but it accepts coordinates for three points. We may try to reconcile this by identifying the first two of those points as "control points" and the last point as a "vertex," but this is an uncommon distinction, and it doesn't hold up: we cannot reconcile it with the meaning of "vertex" incurveVertex()
. [Inconsistency]bezierVertex(x2, y2, x3, y3, x4, y4)
andbezierVertex(x2, y2, z2, x3, y3, z3, x4, y4, z4)
. Each of these signatures looks rather complicated by itself. [Complexity]bezierVertex()
andbezier()
are supported, andcurveVertex()
andcurve()
are supported. We also havequadraticVertex()
, butquadratic()
is not supported. (I've proposed separately that we should introduce a new functionarcVertex()
to address a similar inconsistency; we may want to incorporate that into this issue, but for now I'm assuming we'll address it later.) [Inconsistency]quadraticVertex()
is confusing for multiple reasons. BothquadraticVertex()
andbezierVertex()
produce Bézier curves, but only one of them contains the name "Bézier"; in other words, one function is named after the type of curve while the other is named after the order of the curve. Also, many p5 users are students who will have recently learned in algebra that "the vertex of a quadratic" (a parabola) corresponds to its lowest or highest point; that's not generally true of a vertex specified withquadraticVertex()
. [Inconsistency]vertex()
and specify the next four withquadraticVertex()
, we only have five vertices. We could potentially usevertex()
to specify the sixth vertex at the end, but this is inconsistent with howvertex()
is used everywhere else, and it still requires us to mix command types to create a single primitive. [Inflexibility]curveVertex()
uses a general term for a special shape, which leads to inconsistencies. For example, in the p5 reference, “Curves” is used as a general section heading that includes Béziers, whilecurve()
specifically creates Catmull-Rom splines only. This may lead to confusion. For instance, if we introduce a function such ascurveType()
for different spline implementations, it will be hard to guess whether it applies to all curves or only curves made withcurveVertex()
. [Inconsistency]What's the solution?
The main idea is to pass only one vertex into each vertex function.
Proposed API
The full API is indicated below.
Amazingly, this simple API solves all eleven problems listed above 🤯The basic design was inspired by this comment from @davepagurek.
Notes:
bezierOrder()
eliminates the need forquadraticVertex()
arcVertex()
is based on the latest iteration of #6459splineVertex()
replacescurveVertex()
[^1]Code examples
Example 1: Chained Bézier curves with the current API and the proposed API (3D case). Significance: The proposal employs clear function names, readable parameter lists, and flexible design. Note: Chaining quadratic and cubic Bézier curves does not currently work in p5, but issue #6560 aims to address this.
Example 2: Quad strips (unchanged by proposal) and chained Bézier curves (proposed). Significance: The proposal provides a consistent way of chaining shapes together, across curves, triangles, and quads. Note: Bézier control points are rendered below as a visual aid, but the code for that is not shown.
Pros (updated based on community comments)
arcVertex()
, rather thanvertex()
. Same for other curve types.Cons (updated based on community comments)
Another issue has also been observed that is currently under discussion, but it's not an issue with the API per se. It's based on the usage in the code example.
[^1]: For consistency, we could also rename
curve()
asspline()
. [^2]: Beginners won't tend to know those other APIs, and more experienced users may have less trouble adapting, so this seems like a smaller concern.Proposal status
Under review
Updates
This proposal has been updated to reflect some small adjustments, based on the discussion in the comments section:
bezierOrder()
was added to the API so that chained segments of different orders can be distinguishedarcVertex()
was added based on the current consensus in #6459curveVertex()
was replaced withsplineVertex()
based on Problem 11, which was added to the problem listAdditional code examples have also been included.