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

[Kevin Rushforth]

1) Yes (although CSS and layout won't work properly if no scene...at 
least not for this release).

2) I hadn't planned on it, but that is an excellent suggestion. I will 
make that change (it's trivial). And btw, default viewport is 
boundsInParent for a node snapshot with a null Viewport, the default 
transform is IDENTITY and default fill is WHITE (matching the default on 
Scene).

-- Kevin


Alexander Kouznetsov wrote:
> Hi Kevin,
>
> The proposal looks very reasonable.
>
> I want to clarify a few points:
>
>    1. Does it allow to render nodes that are not part of any Scene?
>       Looks like that.
>    2. Can params be null? Meaning that for the nodes added to scene,
>       its depthbuffer and camera parameters are used to render? It
>       looks like boundsInLocal seems to be a good candidate for the
>       view port in this case. Transform the identity and Fill is
>       TRANSPARENT?
>
> Best regards,
> Alexander Kouznetsov
>
> On 12.05.2012 5:03, Kevin Rushforth wrote:
>> 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.
>>