[whatwg] drawing API

[Oliver Steele]

Hello.  I'm new to the list, but I've looked over the archives and it 
looked like this was the right place to raise discuss this.  Apologies 
in advance if this is off topic.

I am involved with a proposal to add a procedural drawing API to the 
Laszlo RIA platform, a corporate-sponsored open source project hosted 
at http://openlaszlo.org.  We are planning to use, to the extent 
possible, a subset of that WHAT-WG graphics API 
<http://www.whatwg.org/specs/web-apps/current-work/#graphics>, for a 
variety of reasons described on the Drawing API proposal page 
<http://openlaszlo.org/wiki/Drawing_API>.

In looking over the drawing API, I found these names confusing:
   void quadraticCurveTo(in float cpx, in float cpy, in float x, in 
float y);
   void bezierCurveTo(in float cp1x, in float cp1y, in float cp2x, in 
float cp2y, in float x, in float y);
The reason is that (I assume) they both add bezier curves to the open 
path; but only one incorporates "bezier" in its name, and only one 
encodes the order of the bezier curve in its name: the names differ 
differ in that the first is "quadratic" and the second is "bezier", but 
the functionality differs in that the first is quadratic and the second 
is cubic.

A cursory scan of other modern graphics systems (Java2D, Cairo) 
indicates that they have a single curveTo() method, which takes 6 
parameters and specifies a cubic "bezier".  You can specify a quadratic 
"bezier" by using the same value for both control points. This is 
pretty inconvenient in my experience: specification of a quadratic 
bezier is actually a pretty common case.  (It's easier for programmers 
to specify; it's the common case in interactive drawing; and it's the 
only supported bezier order for some systems such as TrueType, the 
Flash rendering engine, and historical systems that have a fond place 
in my heart such as Quickdraw GX and the Alphamask Graphics Library.)

How about using a single variadic curveTo() method?:
   void curveTo(in float cpx, in float cpy, in float x, in float y); // 
quadratic bezier
   void curveTo(in float cp1x, in float cp1y, in float cp2x, in float 
cp2y, in float x, in float y); // cubic bezier
A JavaScript implementation of curveTo could distinguish these based on 
the value of arguments.length.

This would be the most convenient to users of the API, but I don't know 
what your conventions are on variadic methods and whether this has 
implications for non-JavaScript language bindings.  If this is 
unacceptable, what do you about changing the names to be parallel, and 
leaving it implicit that they're bezier's?  (I think all curveTo 
commands in modern vector graphics libraries are beziers.)
   void quadraticCurveTo(in float cpx, in float cpy, in float x, in 
float y);
   void cubicCurveTo(in float cp1x, in float cp1y, in float cp2x, in 
float cp2y, in float x, in float y);

Best,
Oliver

--
Oliver Steele
Chief Software Architect
Laszlo Systems, Inc.