API Review RT:17407 Canvas Node

[Kevin Rushforth]

One thing we should have mentioned up front is that the ImgaeData (and 
ImgFormat) classes are very preliminary, which is why they have started 
out life as "@deprecated". The final form they will take depends on 
http://javafx-jira.kenai.com/browse/RT-17409 .

-- Kevin


Jim Graham wrote:
> 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)
>>