API Review: BufferedImage import/export utilities

[Jim Graham]

Hi Artem,

This will eventually contain a bunch of utilities so Image should not be 
in its name.  Do you have any other suggestions?

SwingFXUtils?
JFXUtils? (to match JFX panel)
JFXSwingUtils? (to differentiate from other embed packages)

			...jim

On 5/21/2012 5:37 AM, Artem Ananiev wrote:
> Hi, Jim,
>
> just a short comment. SwingUtils is very close to well-known
> SwingUtilities from the javax.swing package. Could we use another name,
> e.g. SwingImageUtils?
>
> Thanks,
>
> Artem
>
> On 5/18/2012 11:14 PM, Jim Graham wrote:
>> Now that the Image Ops provide a supported way of manipulating the
>> pixels of an Image, we can add supported methods for managing
>> BufferedImage import and export in the javafx.embed.swing package. I am
>> proposing the following simple utility class for 2.2:
>>
>> package javafx.embed.swing;
>>
>> /**
>> * This class provides utility methods for converting data types between
>> * Swing/AWT and JavaFX formats.
>> */
>> public class SwingUtils {
>> private SwingUtils() {} // no instances
>>
>> /**
>> * Snapshots the specified {@link BufferedImage} and stores a copy of
>> * its pixels into a JavaFX {@link Image} object, creating a new
>> * object if needed.
>> * The returned {@code Image} will be a static snapshot of the state
>> * of the pixels in the {@code BufferedImage} at the time the method
>> * completes. Further changes to the {@code BufferedImage} will not
>> * be reflected in the {@code Image}.
>> * <p>
>> * The optional JavaFX {@link WritableImage} parameter may be reused
>> * to store the copy of the pixels.
>> * A new {@code Image} will be created if the supplied object is null,
>> * is too small or of a type which the image pixels cannot be easily
>> * converted into.
>> *
>> * @param bimg the {@code BufferedImage} object to be converted
>> * @param wimg an optional {@code WritableImage} object that can be
>> * used to store the returned pixel data
>> * @return an {@code Image} object representing a snapshot of the
>> * current pixels in the {@code BufferedImage}.
>> */
>> public static WritableImage toFXImage(BufferedImage bimg,
>> WritableImage wimg);
>>
>> /**
>> * Snapshots the specified JavaFX {@link Image} object and stores a
>> * copy of its pixels into a {@link BufferedImage} object, creating
>> * a new object if needed.
>> * The method will only convert a JavaFX {@code Image} that is readable
>> * as per the conditions on the
>> * {@link Image#getPixelReader() Image.getPixelReader()}
>> * method.
>> * If the {@code Image} is a writable, or other dynamic image, then
>> * the {@code BufferedImage} will only be set to the current state of
>> * the pixels in the image as determined by its {@link PixelReader}.
>> * Further changes to the pixels of the {@code Image} will not be
>> * reflected in the returned {@code BufferedImage}.
>> * <p>
>> * The optional {@code BufferedImage} parameter may be reused to store
>> * the copy of the pixels.
>> * A new {@code BufferedImage} will be created if the supplied object
>> * is null, is too small or of a type which the image pixels cannot
>> * be easily converted into.
>> *
>> * @param img the JavaFX {@code Image} to be converted
>> * @param bimg an optional {@code BufferedImage} object that may be
>> * used to store the returned pixel data
>> * @return a {@code BufferedImage} containing a snapshot of the JavaFX
>> * {@code Image}
>> */
>> public static BufferedImage fromFXImage(Image img,
>> BufferedImage bimg);
>> }
>>
>> ...jim