Spec-Zone .ru
спецификации, руководства, описания, API
001/*
002 * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation.  Oracle designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Oracle in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
022 * or visit www.oracle.com if you need additional information or have any
023 * questions.
024 */
025
026package javafx.scene.image;
027
028import java.nio.Buffer;
029import java.nio.ByteBuffer;
030import java.nio.IntBuffer;
031import javafx.scene.paint.Color;
032
033/**
034 * This interface defines methods for retrieving the pixel data from an
035 * {@link Image} or other surface containing pixels.
036 */
037public interface PixelReader {
038    /**
039     * This method returns the {@code PixelFormat} in which the surface
040     * stores its pixels, or a roughly equivalent pixel format into which
041     * it can easily convert its pixels for purposes of reading them.
042     * 
043     * @return the {@code PixelFormat} that best describes the underlying
044     *         pixels
045     */
046    public PixelFormat getPixelFormat();
047
048    /**
049     * Reads a 32-bit integer representation of the color of a pixel
050     * from the specified coordinates in the surface.
051     * The 32-bit integer will contain the 4 color components in separate
052     * 8-bit fields in ARGB order from the most significant byte to the least
053     * significant byte.
054     * 
055     * @param x the X coordinate of the pixel color to read
056     * @param y the Y coordinate of the pixel color to read
057     * @return a 32-bit representation of the color in the format
058     *         described by the {@link PixelFormat.Type#INT_ARGB INT_ARGB}
059     *         PixelFormat type.
060     */
061    public int getArgb(int x, int y);
062
063    /**
064     * Reads the color of a pixel from the specified coordinates in the
065     * surface and returns the value as a {@link Color} object.
066     * 
067     * @param x the X coordinate of the pixel color to read
068     * @param y the Y coordinate of the pixel color to read
069     * @return the Color object representing the color of the indicated
070     *         pixel
071     */
072    public Color getColor(int x, int y);
073
074    /**
075     * Reads pixel data from a rectangular region of the surface into the
076     * specified buffer.
077     * The format to be used for pixels in the buffer is defined by the
078     * {@link PixelFormat} object and pixel format conversions will be
079     * performed as needed to store the data in the indicated format.
080     * The buffer is assumed to be positioned to the location where the
081     * first pixel data from the image pixel at location {@code (x, y)}
082     * will be stored.
083     * Pixel data for a row will be stored in adjacent locations within
084     * the buffer packed as tightly as possible for increasing X
085     * coordinates.
086     * Pixel data for adjacent rows will be stored offset from each other
087     * by the number of buffer data elements defined by
088     * {@code scanlineStride}.
089     * 
090     * @param x the X coordinate of the rectangular region to read
091     * @param y the Y coordinate of the rectangular region to read
092     * @param w the width of the rectangular region to read
093     * @param h the height of the rectangular region to read
094     * @param pixelformat the {@code PixelFormat} object defining the format
095     *        to store the pixels into buffer
096     * @param buffer a buffer of a type appropriate for the indicated
097     *        {@code PixelFormat} object
098     * @param scanlineStride the distance between the pixel data for the
099     *        start of one row of data in the buffer to the start of the
100     *        next row of data.
101     */
102    public <T extends Buffer>
103        void getPixels(int x, int y, int w, int h,
104                       WritablePixelFormat<T> pixelformat,
105                       T buffer, int scanlineStride);
106
107    /**
108     * Reads pixel data from a rectangular region of the surface into the
109     * specified byte array.
110     * The format to be used for pixels in the buffer is defined by the
111     * {@link PixelFormat} object and pixel format conversions will be
112     * performed as needed to store the data in the indicated format.
113     * The {@code pixelformat} must be a compatible
114     * {@code PixelFormat<ByteBuffer>} type.
115     * The data for the first pixel at location {@code (x, y)} will be
116     * read into the array index specified by the {@code offset} parameter.
117     * Pixel data for a row will be stored in adjacent locations within
118     * the array packed as tightly as possible for increasing X
119     * coordinates.
120     * Pixel data for adjacent rows will be stored offset from each other
121     * by the number of byte array elements defined by
122     * {@code scanlineStride}.
123     * 
124     * @param x the X coordinate of the rectangular region to read
125     * @param y the Y coordinate of the rectangular region to read
126     * @param w the width of the rectangular region to read
127     * @param h the height of the rectangular region to read
128     * @param pixelformat the {@code PixelFormat<ByteBuffer>} object
129     *        defining the byte format to store the pixels into buffer
130     * @param buffer a byte array to store the returned pixel data
131     * @param offset the offset into {@code buffer} to store the first
132     *        pixel data
133     * @param scanlineStride the distance between the pixel data for the
134     *        start of one row of data in the buffer to the start of the
135     *        next row of data
136     */
137    public void getPixels(int x, int y, int w, int h,
138                          WritablePixelFormat<ByteBuffer> pixelformat,
139                          byte buffer[], int offset, int scanlineStride);
140
141    /**
142     * Reads pixel data from a rectangular region of the surface into the
143     * specified int array.
144     * The format to be used for pixels in the buffer is defined by the
145     * {@link PixelFormat} object and pixel format conversions will be
146     * performed as needed to store the data in the indicated format.
147     * The {@code pixelformat} must be a compatible
148     * {@code PixelFormat<IntBuffer>} type.
149     * The data for the first pixel at location {@code (x, y)} will be
150     * read into the array index specified by the {@code offset} parameter.
151     * Pixel data for a row will be stored in adjacent locations within
152     * the array packed as tightly as possible for increasing X
153     * coordinates.
154     * Pixel data for adjacent rows will be stored offset from each other
155     * by the number of int array elements defined by
156     * {@code scanlineStride}.
157     * 
158     * @param x the X coordinate of the rectangular region to read
159     * @param y the Y coordinate of the rectangular region to read
160     * @param w the width of the rectangular region to read
161     * @param h the height of the rectangular region to read
162     * @param pixelformat the {@code PixelFormat<IntBuffer>} object
163     *        defining the int format to store the pixels into buffer
164     * @param buffer a int array to store the returned pixel data
165     * @param offset the offset into {@code buffer} to store the first
166     *        pixel data
167     * @param scanlineStride the distance between the pixel data for the
168     *        start of one row of data in the buffer to the start of the
169     *        next row of data
170     */
171    public void getPixels(int x, int y, int w, int h,
172                          WritablePixelFormat<IntBuffer> pixelformat,
173                          int buffer[], int offset, int scanlineStride);
174}