API REVIEW request for RT-17398: snapshot (aka render to image)

[Kevin Rushforth]

JIRA:  http://javafx-jira.kenai.com/browse/RT-17398

This feature request will add public API to support taking a snapshot of 
a Scene or Node and rendering it into an Image.

To address this feature, I propose to add the following methods on the 
existing Node and Scene class, along with two new classes to hold the 
parameters and the result, respectively.

Scene:
    public Image snapshot(Image image)
    public void snapshot(Callback<SnapshotResult,Void> callback, Image 
image)

Node:
    public Image snapshot(SnapshotParameters params, Image image)
    public void snapshot(Callback<SnapshotResult,Void> callback, 
SnapshotParameters params, Image image)

// Data container class with the following attributes
SnapshotParameters:
    get/setDepthBuffer(boolean)
    get/setCamera(Camera)
    get/setTransform(Transform);
    get/setFill(Paint);
    get/setViewport(Rectangle2D)

// Data container class to return the result of an async snapshot, 
currently immutable
SnapshotResult:
    Image image
    Object source
    SnapshotParameters params


Here is the preliminary Javadoc for the four snapshot methods:

-------------------------------------------------------------------

Scene:
    public Image snapshot(Image image)

Takes a snapshot of this scene and returns the rendered image when it is 
ready. CSS and layout processing will be done for the scene prior to 
rendering it.

    image - the image that will be used to hold the rendered scene. It 
may be null in which case a new Image will be constructed. If the image 
is non-null, the scene will be rendered into the existing image. If the 
image is larger than the scene, the area outside the bounds of the scene 
will be filled with the Scene fill color. If the image is smaller than 
the scene, the rendered image will be clipped.

-------------------------------------------------------------------

Scene:
    public void snapshot(Callback<SnapshotResult,Void> callback, Image 
image)

Takes a snapshot of this scene at the next frame and calls the specified 
callback method when the image is ready. CSS and layout processing will 
be done for the scene prior to rendering it. This is an asynchronous 
call, which means that other events or animation might be processed 
before the scene is rendered. If any such events modify a node in the 
scene that modification will be reflected in the rendered image (as it 
will also be reflected in the frame rendered to the Stage).

    callback - a class whose call method will be called when the image 
is ready. The SnapshotResult that is passed into the call method of the 
callback will contain the rendered image and the source scene that was 
rendered.

    image - the image that will be used to hold the rendered scene. It 
may be null in which case a new Image will be constructed. If the image 
is non-null, the scene will be rendered into the existing image. If the 
image is larger than the scene, the area outside the bounds of the scene 
will be filled with the Scene fill color. If the image is smaller than 
the scene, the rendered image will be clipped.

-------------------------------------------------------------------

Node:
    public Image snapshot(SnapshotParameters params, Image image)

Takes a snapshot of this node and returns the rendered image when it is 
ready. CSS and layout processing will be done for the node, and any of 
its children, prior to rendering it.

Parameters:
    params - the snapshot parameters containing attributes that will 
control the rendering.

    image - the image that will be used to hold the rendered node. It 
may be null in which case a new Image will be constructed. If the image 
is non-null, the node will be rendered into the existing image. If the 
image is larger than the bounds of the node, the area outside the bounds 
will be filled with the fill color specified in the snapshot parameters. 
If the image is smaller than the bounds, the rendered image will be clipped.

-------------------------------------------------------------------

Node:
    public void snapshot(Callback<SnapshotResult,Void> callback, 
SnapshotParameters params, Image image)

Takes a snapshot of this node at the next frame and calls the specified 
callback method when the image is ready. CSS and layout processing will 
be done for the node, and any of its children, prior to rendering it. 
This is an asynchronous call, which means that other events or animation 
might be processed before the node is rendered. If any such events 
modify the node, or any of its children, that modification will be 
reflected in the rendered image (just like it will also be reflected in 
the frame rendered to the Stage, if this node is part of a live scene 
graph).

    callback - a class whose call method will be called when the image 
is ready. The SnapshotResult that is passed into the call method of the 
callback will contain the rendered image, the source node that was 
rendered, and a copy of the SnapshotParameters.

    params - the snapshot parameters containing attributes that will 
control the rendering.

    image - the image that will be used to hold the rendered node. It 
may be null in which case a new Image will be constructed. If the image 
is non-null, the node will be rendered into the existing image. If the 
image is larger than the bounds of the node, the area outside the bounds 
will be filled with the fill color specified in the snapshot parameters. 
If the image is smaller than the bounds, the rendered image will be clipped.