API review - Image Ops (RT-17409)
Kevin Rushforth
kevin.rushforth at oracle.com
Mon May 14 19:29:47 PDT 2012
Looks good to me.
One question: often a value of 0 for stride is used to mean "pack
adjacent rows as tightly as possible" (possibly subject to alignment
rules for pixel data with less than 4 components per pixel). Do you plan
to support that?
-- Kevin
Jim Graham wrote:
> http://javafx-jira.kenai.com/browse/RT-17409
>
> I've added a couple of new classes and a small number of new methods
> to provide pixel access to images. I am not yet done with the
> implementation so I can't really share a webrev yet, but I need to get
> the API approved before our API freeze, so here are the new classes
> and methods:
>
> javafx.scene.image.Image (new methods):
>
> /**
> * Construct a new empty {@code Image} with the specified dimensions
> * filled with transparent pixels to be used with the
> * {@link #setArgb(int, int, int) setArgb()}
> * and
> * {@link #setColor(int, int, javafx.scene.paint.Color) setColor()}
> * methods to create a completely custom image.
> *
> * @param width the width of the empty image
> * @param height the height of the empty image
> */
> public Image(int width, int height);
>
> /**
> * This method returns the {@code PixelFormat} in which the image
> stores
> * its pixels, or a roughly equivalent pixel format into which it can
> * easily convert its pixels for purposes of reading and writing
> them.
> * If this method returns null then this image does not support
> reading
> * and writing of pixels in any format and all of the methods to
> * get and set pixels will throw an {@link
> UnsupportedOperationException}.
> * This method will return null if the image is being loaded from a
> * source and is still incomplete {the progress is still < 1.0) or if
> * there was an error.
> * This method may also return null for some images in a format that
> * is not supported for reading and writing pixels to.
> *
> * @return the {@code PixelFormat} that best describes the underlying
> * pixels
> */
> public PixelFormat getPixelFormat() {
>
> /**
> * Reads a 32-bit integer representation of the color of a pixel
> * from the specified coordinates in the image.
> * The 32-bit integer will contain the 4 color components in separate
> * 8-bit fields in ARGB order from the most significant byte to
> the least
> * significant byte.
> *
> * @param x the X coordinate of the pixel color to read
> * @param y the Y coordinate of the pixel color to read
> * @return a 32-bit representation of the color in a format described
> * by the {@link PixelFormat.Type.BYTE_ARGB} PixelFormat
> type.
> * @throws UnsupportedOperationException if the image pixels are not
> * accessible
> * @see #getPixelFormat()
> */
> public int getArgb(int x, int y) {
> return checkPixelAccess(true, false).getArgb(x, y);
> }
>
> /**
> * Reads the color of a pixel from the specified coordinates in the
> * image and returns the value as a {@link Color} object.
> *
> * @param x the X coordinate of the pixel color to read
> * @param y the Y coordinate of the pixel color to read
> * @return the Color object representing the color of the indicated
> * pixel
> * @throws UnsupportedOperationException if the image pixels are not
> * accessible
> * @see #getPixelFormat()
> */
> public Color getColor(int x, int y);
>
> * Stores pixel data for a color into the specified coordinates of
> the
> * image.
> * The 32-bit integer {@code argb} parameter will contain the 4 color
> * components in separate 8-bit fields in ARGB order from the most
> * significant byte to the least significant byte.
> *
> * @param x the X coordinate of the pixel color to write
> * @param y the Y coordinate of the pixel color to write
> * @param argb the color information to write, specified in a format
> * described by the {@link PixelFormat.Type.BYTE_ARGB}
> * PixelFormat type.
> * @throws UnsupportedOperationException if the image pixels are not
> * accessible
> * @see #getPixelFormat()
> */
> public void setArgb(int x, int y, int argb);
>
> /**
> * Stores pixel data for a {@link Color} into the specified
> coordinates
> * of the image.
> *
> * @param x the X coordinate of the pixel color to write
> * @param y the Y coordinate of the pixel color to write
> * @param c the Color to write
> * @throws UnsupportedOperationException if the image pixels are not
> * accessible
> * @see #getPixelFormat()
> */
> public void setColor(int x, int y, Color c);
>
> /**
> * Reads pixel data from a rectangular region of the image into the
> * specified buffer.
> * The format of the pixels in the buffer are defined by the
> * {@link PixelFormat} object and pixel format conversions will be
> * performed as needed.
> * The buffer is assumed to be positioned to the location where the
> * first pixel data from the image pixel at location {@code (x, y)}
> * will be stored.
> * Pixel data for a row will be stored in adjacent locations within
> * the buffer packed as tightly as possible for increasing X
> * coordinates.
> * Pixel data for adjacent rows will be stored offset from each other
> * by the number of buffer data elements defined by
> * {@code scanlineStride}.
> *
> * @param x the X coordinate of the rectangular region to read
> * @param y the Y coordinate of the rectangular region to read
> * @param w the width of the rectangular region to read
> * @param h the height of the rectangular region to read
> * @param buffer a buffer of a type appropriate for the indicated
> * {@code PixelFormat} object
> * @param pixelformat the {@code PixelFormat} object defining the
> format
> * to store the pixels into buffer
> * @param scanlineStride the distance between the pixel data for the
> * start of one row of data in the buffer to the start of the
> * next row of data.
> * @throws UnsupportedOperationException if the image pixels are not
> * accessible
> * @see #getPixelFormat()
> */
> public <T extends Buffer>
> void getPixels(int x, int y, int w, int h,
> T buffer, WritablePixelFormat<T> pixelformat,
> int scanlineStride);
>
> /**
> * Stores pixel data from a buffer into a rectangular region of the
> * image.
> * The format of the pixels in the buffer are defined by the
> * {@link PixelFormat} object and pixel format conversions will be
> * performed as needed.
> * The buffer is assumed to be positioned to the location where the
> * first pixel data to be stored in the image pixel at location
> * {@code (x, y)} is located.
> * Pixel data for a row will be stored in adjacent locations within
> * the buffer packed as tightly as possible for increasing X
> * coordinates.
> * Pixel data for adjacent rows will be stored offset from each other
> * by the number of buffer data elements defined by
> * {@code scanlineStride}.
> *
> * @param x the X coordinate of the rectangular region to write
> * @param y the Y coordinate of the rectangular region to write
> * @param w the width of the rectangular region to write
> * @param h the height of the rectangular region to write
> * @param buffer a buffer of a type appropriate for the indicated
> * {@code PixelFormat} object
> * @param pixelformat the {@code PixelFormat} object defining the
> format
> * of the pixels in the buffer
> * @param scanlineStride the distance between the pixel data for the
> * start of one row of data in the buffer to the start of the
> * next row of data.
> * @throws UnsupportedOperationException if the image pixels are not
> * accessible
> * @see #getPixelFormat()
> */
> public <T extends Buffer>
> void setPixels(int x, int y, int w, int h,
> T buffer, PixelFormat<T> pixelformat,
> int scanlineStride);
>
> =========================================================
>
> javafx.scene.image.PixelFormat:
>
> /**
> * A {@code PixelFormat} object defines the layout of data for a pixel of
> * a given format.
> */
> public abstract class PixelFormat<T extends Buffer> {
> public enum Type {
> /**
> * The pixels are stored in 32-bit integers with the
> premultiplied
> * components stored in order, from MSb to LSb:
> * alpha, red, green, blue.
> */
> INT_ARGB_PRE,
> /**
> * The pixels are stored in 32-bit integers with the
> non-premultiplied
> * components stored in order, from MSb to LSb:
> * alpha, red, green, blue.
> */
> INT_ARGB,
> /**
> * The pixels are stored in adjacent bytes with the premultiplied
> * components stored in order of increasing index:
> * blue, green, red, alpha.
> */
> BYTE_BGRA_PRE,
> /**
> * The pixels are stored in adjacent bytes with the
> non-premultiplied
> * components stored in order of increasing index:
> * blue, green, red, alpha.
> */
> BYTE_BGRA,
> /**
> * The opaque pixels are stored in adjacent bytes with the color
> * components stored in order of increasing index:
> * red, gree, blue.
> */
> BYTE_RGB,
> /**
> * The pixel colors are referenced by byte indices stored in the
> * pixel array, with the byte interpreted as an unsigned index
> into
> * a list of colors provided by the {@code PixelFormat} object.
> */
> BYTE_INDEXED,
> }
>
> // Static factory methods
> public static WritablePixelFormat<IntBuffer> getArgbInstance();
>
> public static WritablePixelFormat<IntBuffer> getArgbPreInstance();
>
> public static WritablePixelFormat<ByteBuffer> getByteBgraInstance();
>
> public static WritablePixelFormat<ByteBuffer>
> getByteBgraPreInstance();
>
> public static PixelFormat<ByteBuffer> getByteRgbInstance();
>
> public static PixelFormat<ByteBuffer>
> createByteIndexedPremultipliedInstance(int colors[]);
>
> public static PixelFormat<ByteBuffer>
> createByteIndexedInstance(int colors[]);
>
> // Informational getters
> public Type getType();
>
> public boolean isWritable();
>
> public boolean isPremultiplied();
>
> // Pixel access methods
>
> /**
> * Reads a 32-bit integer representation of the color from the buffer
> * at the specified coordinates.
> * The 32-bit integer will contain the 4 color components in separate
> * 8-bit fields in ARGB order from the most significant byte to
> the least
> * significant byte.
> * The buffer should be positioned to the start of the pixel data
> such
> * that {@code buf.get(0)} would return the pixel information for the
> * pixel at coordinates {@code (0, 0)}.
> * The {@scanlineStride} parameter defines the distance from the
> pixel
> * data at the start of one row to the pixel data at the start of the
> * immediately following row at the next higher Y coordinate.
> Usually,
> * {@scanlineStride} is the same as the width of the image multiplied
> * by the number of data elements per pixel (1 for the case of the
> * integer and indexed formats, or 3 or 4 in the case of the byte
> * formats), but some images may have further padding between rows
> for
> * alignment or other purposes.
> *
> * @param buf the buffer of pixel data
> * @param x the X coordinate of the pixel to be read
> * @param y the Y coordinate of the pixel to be read
> * @param scanlineStride the number of buffer elements between the
> * start of adjacent pixel rows in the buffer
> * @return a 32-bit value with the color of the pixel in a format
> * similar to the {@code Type.INT_ARGB} pixel format
> */
> public abstract int getArgb(T buf, int x, int y, int scanlineStride);
> }
>
> =========================================================
>
> javafx.scene.image.WritablePixelFormat:
>
> /**
> * A {@link PixelFormat} object representing a pixel format that can
> store
> * full colors and so can be used as a destination format to write pixel
> * data from an arbitrary image.
> */
> public abstract class WritablePixelFormat<T extends Buffer>
> extends PixelFormat<T>
> {
> /**
> * Stores a 32-bit integer representation of the color in the buffer
> * at the specified coordinates.
> ... Similar wording to the getArgb method above...
> * @param argb a 32-bit value with the color to be stored in the
> pixel
> * in a format similar to the {@code Type.INT_ARGB} pixel
> format
> */
> public abstract void setArgb(T buf, int x, int y, int scanlineStride,
> int argb);
> }
>
> =========================================================
>
> ...jim
More information about the openjfx-dev
mailing list