API Review RT:17407 Canvas Node

[Jim Graham]

First, while the API gives heavy nods to the overall feel of the HTML5 
Canvas graphics API, this is not meant to be a duplicate of that API. 
Instead we want to provide an API that serves the needs of any of:

- HTML5 Canvas programs and their developers
- AWT Canvas programs and their developers
- SVG programs and developers
- any number of similar immediate mode APIs that we've seen over the years

But, we wanted it to be an API that fit well with existing FX paradigms. 
  This is the FX version of immediate mode graphics, but with a strong 
nod to familiarity of those other APIs.  It is most like the HTML5 APIs 
because that was at the top of our priority list, but it isn't an HTML5 
clone, just like it is fairly far from being an AWT/Java2D clone.

To that end, we have a number of places where we are "just like HTML5, 
but with an FX parameter or object".

- fill and stroke paints are FX Paint objects: Color, LinearGradient, 
RadialGradient
   (when we provide a public ImagePattern paint object, that will work too)
- rendering png/jpeg/etc images uses the FX Image object, not an HTML entity
- angles are in degrees like FX objects, not radians like HTML5

Some areas where we broke from FX, but are still contemplating if that 
was the right move:

- a separate composite mode which largely duplicates the Blend modes 
used on Nodes, but is its own enum
   (basically HTML5 provided some blend modes which we weren't happy 
providing in our scene graph, so I punted for the short term, but we may 
switch back to the FX Blend.Mode values before we finalize - pros? cons? 
opinions?)
- we provided some prototype ImageData facilities to test usefulness of 
manipulatable image buffers, but we eventually want to replace those 
with whatever we do for the FX scene graph ImageOps API so we deprecated 
these but left them in for playing around with until we finish that task.
- we are waiting on getImageData which provides read-back support until 
we finalize official support for "Node to image" and then will provide 
something similar there.  We didn't even provide a prototype for playing 
in this case.

Some HTML5 oddities that I borrowed, but don't necessarily like:

- current path is not part of save/restore states per HTML5 spec, but 
I'm not sure why they do it that way
- stateful path construction where every element can be in a different 
coordinate system as opposed to providing a separate path object that is 
evaluated in its entirety in the current coordinate system at the time 
it is rendered

Some things we added from 2D and SVG:

- fill/draw/oval/poly*/roundrect/arc
- appendSVGPath

Some things we added from other legacy immediate mode APIs:

- nothing that I remember - any suggestions?  (Only minor additions can 
be considered for this release due to time constraints, but discussions 
leading to Jira entries are always good.)

Does that help answer your questions?

		...jim

On 4/18/12 10:47 PM, Vasiliy Baranov wrote:
> Hi Joe,
>
> The GraphicsContext.getImageData method is not on the list. Is that
> intentional?
>
> The GraphicsContext.createImageData methods are missing from the list
> below but are listed in the attached docs. I suppose they are to be
> included, otherwise there is little value in putImageData?
>
> A few other HTML5 CanvasRenderingContext2D methods are also missing:
> createLinearGradient, createRadialGradient, createPattern. Is equivalent
> functionality going to be available elsehow?
>
> Thank you,
> -- Vasiliy
>
> On 19.04.2012 2:36, joe andresen wrote:
>> Hello Everyone,
>>
>> We propose to add a Canvas node and GraphicsContext to a new
>> javafx.scene.canvas package for JavaFX 2.2. The javafx.scene.canvas
>> package provides a pair of classes for an immediate mode style API for
>> rendering. Canvas Node works seemlessly with effects as well as
>> Animation timers, and will be tightly bound to the new ImageOps API.
>>
>> This new API will allow HTML5 Canvas users to easily port their existing
>> applications that make heavy use of the HTML5 canvas directly to JavaFX
>> without the need to morph their application to fit the scenegraph model.
>>
>> You can Download and unzip the (preliminary) relevant docs here:
>> JIRA: http://javafx-jira.kenai.com/browse/RT-17407
>>
>> Note that the docs are a work in progress but should be enough for API
>> Review. (Also, Jira will be down Thursday 4/19 at 1400 PDT for a while).
>>
>> A list of the the methods for Canvas and GraphicsContext are listed
>> below.
>>
>> Canvas:
>>
>> GraphicsContext getGraphicsContext2D()
>> double getHeight()
>> double getWidth()
>> DoubleProperty heightProperty()
>> void setHeight(double value)
>> void setWidth(double value)
>> DoubleProperty widthProperty()
>>
>> GraphicsContext:
>> void appendSVGPath(java.lang.String svgpath)
>> void applyEffect(Effect e)
>> void arc(double centerX, double centerY, double radiusX, double radiusY,
>> double startAngle, double length)
>> void arcTo(double x1, double y1, double x2, double y2, double radius)
>> void beginPath()
>> void bezierCurveTo(double xc1, double yc1, double xc2, double yc2,
>> double x1, double y1)
>> void clearRect(double x, double y, double w, double h)
>> void clip()
>> void closePath()
>> void drawArc(double x, double y, double w, double h, double startAngle,
>> double arcExtent, ArcType closure)
>> void drawImage(Image img, double x, double y)
>> void drawImage(Image img, double x, double y, double w, double h)
>> void drawImage(Image img, double sx, double sy, double sw, double sh,
>> double dx, double dy, double dw, double dh)
>> void drawLine(double x1, double y1, double x2, double y2)
>> void drawOval(double x, double y, double w, double h)
>> void drawPolygon(double[] xPoints, double[] yPoints, int nPoints)
>> void drawPolyline(double[] xPoints, double[] yPoints, int nPoints)
>> void drawRoundRect(double x, double y, double w, double h, double
>> arcWidth, double arcHeight)
>> void fill()
>> void fillArc(double x, double y, double w, double h, double startAngle,
>> double arcExtent, ArcType closure)
>> void fillOval(double x, double y, double w, double h)
>> void fillPolygon(double[] xPoints, double[] yPoints, int nPoints)
>> void fillRect(double x, double y, double w, double h)
>> void fillRoundRect(double x, double y, double w, double h, double
>> arcWidth, double arcHeight)
>> void fillText(java.lang.String text, double x, double y)
>> void fillText(java.lang.String text, double x, double y, double maxWidth)
>> Canvas getCanvas()
>> boolean isPointInPath(double x, double y)
>> void lineTo(double x1, double y1)
>> double measureText(java.lang.String text)
>> void moveTo(double x0, double y0)
>> void putImageData(GraphicsContext.ImageData imagedata, double dx, double
>> dy)
>> void putImageData(GraphicsContext.ImageData imagedata, double dx, double
>> dy, double dirtyX, double dirtyY, double dirtyWidth, double dirtyHeight)
>> void quadraticCurveTo(double xc, double yc, double x1, double y1)
>> void rect(double x, double y, double w, double h)
>> void restore()
>> void rotate(double degrees)
>> void save()
>> void scale(double x, double y)
>> void setEffect(Effect e)
>> void setFill(Paint p)
>> void setFont(Font f)
>> void setGlobalAlpha(double alpha)
>> void setGlobalCompositeOperation(GraphicsContext.CompositeOperation op)
>> void setLineCap(StrokeLineCap cap)
>> void setLineJoin(StrokeLineJoin join)
>> void setLineWidth(double lw)
>> void setMiterLimit(double ml)
>> void setStroke(Paint p)
>> void setTextAlign(TextAlignment align)
>> void setTextBaseline(VPos baseline)
>> void setTransform(double mxx, double myx, double mxy, double myy, double
>> mxt, double myt)
>> void stroke()
>> void strokeRect(double x, double y, double w, double h)
>> void strokeText(java.lang.String text, double x, double y)
>> void strokeText(java.lang.String text, double x, double y, double
>> maxWidth)
>> void transform(double mxx, double myx, double mxy, double myy, double
>> mxt, double myt)
>> void translate(double x, double y)
>