API Review: BufferedImage import/export utilities

[Kevin Rushforth]

 > So SwingFXUtils (or SwingFXUtilities) is probably fine.

I recommend the former since we have used XXXUtils in a couple other 
places in our API.

Richard, are you OK with this?

-- Kevin


Artem Ananiev wrote:
>
> On 5/21/2012 11:16 PM, Jim Graham wrote:
>> 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)
>
> I don't think it should start with "J" as it's not a JComponent 
> subclass like JFXPanel. So SwingFXUtils (or SwingFXUtilities) is 
> probably fine.
>
> Thanks,
>
> Artem
>
>> ...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