1 /*
2 * Copyright (c) 2012, 2014, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javafx.scene.image;
27
28 import javafx.scene.paint.Color;
29
30 import java.nio.Buffer;
31 import java.nio.ByteBuffer;
32 import java.nio.IntBuffer;
33
34 /**
35 * This interface defines methods for writing the pixel data of a
36 * {@link WritableImage} or other surface containing writable pixels.
37 * @since JavaFX 2.2
38 */
39 public interface PixelWriter {
40 /**
41 * This method returns the {@code PixelFormat} in which the surface
42 * stores its pixels, or a roughly equivalent pixel format from which
43 * it can easily convert pixels for purposes of writing them.
44 *
45 * @return the {@code PixelFormat} that best describes the underlying
46 * pixels
47 */
48 public PixelFormat getPixelFormat();
49
50 /**
51 * Stores pixel data for a color into the specified coordinates of the
52 * surface.
53 * The 32-bit integer {@code argb} parameter should contain the 4 color
54 * components in separate 8-bit fields in ARGB order from the most
55 * significant byte to the least significant byte.
56 *
57 * @param x the X coordinate of the pixel color to write
58 * @param y the Y coordinate of the pixel color to write
59 * @param argb the color information to write, specified in the format
60 * described by the {@link PixelFormat.Type#INT_ARGB INT_ARGB}
61 * PixelFormat type.
62 */
63 public void setArgb(int x, int y, int argb);
64
65 /**
66 * Stores pixel data for a {@link Color} into the specified coordinates
67 * of the surface.
68 *
69 * @param x the X coordinate of the pixel color to write
70 * @param y the Y coordinate of the pixel color to write
71 * @param c the Color to write or null
72 *
73 * @throws java.lang.NullPointerException if {@code color} is {@code null}
74 */
75 public void setColor(int x, int y, Color c);
76
77 /**
78 * Stores pixel data from a buffer into a rectangular region of the
79 * surface.
80 * The format of the pixels in the buffer is defined by the
81 * {@link PixelFormat} object and pixel format conversions will be
82 * performed as needed to store the data into the surface.
83 * The buffer is assumed to be positioned to the location where the
84 * first pixel data to be stored in the surface pixel at location
85 * {@code (x, y)} is located.
86 * Pixel data for a row will be read from adjacent locations within
87 * the buffer packed as tightly as possible for increasing X
88 * coordinates.
89 * Pixel data for adjacent rows will be read offset from each other
90 * by the number of buffer data elements defined by
91 * {@code scanlineStride}.
92 *
93 * @param x the X coordinate of the rectangular region to write
94 * @param y the Y coordinate of the rectangular region to write
95 * @param w the width of the rectangular region to write
96 * @param h the height of the rectangular region to write
97 * @param pixelformat the {@code PixelFormat} object defining the format
98 * to read the pixels from the buffer
99 * @param buffer a buffer of a type appropriate for the indicated
100 * {@code PixelFormat} object
101 * @param scanlineStride the distance between the pixel data for the
102 * start of one row of data in the buffer to the start of the
103 * next row of data.
104 *
105 * @throws java.lang.NullPointerException if @{code pixelformat} or {@code buffer} is {@code null}
106 */
107 public <T extends Buffer>
108 void setPixels(int x, int y, int w, int h,
109 PixelFormat<T> pixelformat,
110 T buffer, int scanlineStride);
111
112 /**
113 * Stores pixel data from a byte array into a rectangular region of the
114 * surface.
115 * The format of the pixels in the buffer is defined by the
116 * {@link PixelFormat} object and pixel format conversions will be
117 * performed as needed to store the data into the surface.
118 * The {@code pixelformat} must be a compatible
119 * {@code PixelFormat<ByteBuffer>} type.
120 * The data for the first pixel at location {@code (x, y)} will be
121 * read from the array index specified by the {@code offset} parameter.
122 * Pixel data for a row will be read from adjacent locations within
123 * the array packed as tightly as possible for increasing X
124 * coordinates.
125 * Pixel data for adjacent rows will be read offset from each other
126 * by the number of byte array elements defined by
127 * {@code scanlineStride}.
128 *
129 * @param x the X coordinate of the rectangular region to write
130 * @param y the Y coordinate of the rectangular region to write
131 * @param w the width of the rectangular region to write
132 * @param h the height of the rectangular region to write
133 * @param pixelformat the {@code PixelFormat<ByteBuffer>} object
134 * defining the byte format to read the pixels from buffer
135 * @param buffer a byte array containing the pixel data to store
136 * @param offset the offset into {@code buffer} to read the first
137 * pixel data
138 * @param scanlineStride the distance between the pixel data for the
139 * start of one row of data in the buffer to the start of the
140 * next row of data
141 *
142 * @throws java.lang.NullPointerException if @{code pixelformat} or {@code buffer} is {@code null}
143 */
144 public void setPixels(int x, int y, int w, int h,
145 PixelFormat<ByteBuffer> pixelformat,
146 byte buffer[], int offset, int scanlineStride);
147
148 /**
149 * Stores pixel data from an int array into a rectangular region of the
150 * surface.
151 * The format of the pixels in the buffer is defined by the
152 * {@link PixelFormat} object and pixel format conversions will be
153 * performed as needed to store the data into the surface.
154 * The {@code pixelformat} must be a compatible
155 * {@code PixelFormat<IntBuffer>} type.
156 * The data for the first pixel at location {@code (x, y)} will be
157 * read from the array index specified by the {@code offset} parameter.
158 * Pixel data for a row will be read from adjacent locations within
159 * the array packed as tightly as possible for increasing X
160 * coordinates.
161 * Pixel data for adjacent rows will be read offset from each other
162 * by the number of int array elements defined by
163 * {@code scanlineStride}.
164 *
165 * @param x the X coordinate of the rectangular region to write
166 * @param y the Y coordinate of the rectangular region to write
167 * @param w the width of the rectangular region to write
168 * @param h the height of the rectangular region to write
169 * @param pixelformat the {@code PixelFormat<IntBuffer>} object
170 * defining the int format to read the pixels from buffer
171 * @param buffer an int array to containing the pixel data to store
172 * @param offset the offset into {@code buffer} to read the first
173 * pixel data
174 * @param scanlineStride the distance between the pixel data for the
175 * start of one row of data in the buffer to the start of the
176 * next row of data
177 *
178 * @throws java.lang.NullPointerException if @{code pixelformat} or {@code buffer} is {@code null}
179 */
180 public void setPixels(int x, int y, int w, int h,
181 PixelFormat<IntBuffer> pixelformat,
182 int buffer[], int offset, int scanlineStride);
183
184 /**
185 * Stores pixel data retrieved from a {@code PixelReader} instance
186 * into a rectangular region of the surface.
187 * The data for the pixel on the surface at {@code (dstx, dsty)}
188 * will be retrieved from the {@code reader} from its location
189 * {@code (srcx, srcy)}.
190 * This method performs an operation which is semantically equivalent to
191 * (though likely much faster than) this pseudo-code:
192 * <pre>
193 * for (int y = 0; y < h, y++) {
194 * for (int x = 0; x < w; x++) {
195 * setArgb(dstx + x, dsty + y,
196 * reader.getArgb(srcx + x, srcy + y));
197 * }
198 * }
199 * </pre>
200 *
201 *
202 * @param dstx the X coordinate of the rectangular region to write
203 * @param dsty the Y coordinate of the rectangular region to write
204 * @param w the width of the rectangular region to write
205 * @param h the height of the rectangular region to write
206 * @param reader the {@link PixelReader} used to get the pixel data
207 * to write
208 * @param srcx the X coordinate of the data to read from {@code reader}
209 * @param srcy the Y coordinate of the data to read from {@code reader}
210 *
211 * @throws java.lang.NullPointerException if @{code reader} is {@code null}
212 */
213 public void setPixels(int dstx, int dsty, int w, int h,
214 PixelReader reader, int srcx, int srcy);
215 }