1/*
2 * Copyright (c) 1995, 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
26package java.awt.image;
27
28import java.awt.image.ImageConsumer;
29import java.awt.image.ImageProducer;
30import java.awt.image.ColorModel;
31import java.util.Hashtable;
32import java.util.Vector;
33import java.util.Enumeration;
34
35/**
36 * This class is an implementation of the ImageProducer interface which
37 * uses an array to produce pixel values for an Image.  Here is an example
38 * which calculates a 100x100 image representing a fade from black to blue
39 * along the X axis and a fade from black to red along the Y axis:
40 * <pre>{@code
41 *
42 *      int w = 100;
43 *      int h = 100;
44 *      int pix[] = new int[w * h];
45 *      int index = 0;
46 *      for (int y = 0; y < h; y++) {
47 *          int red = (y * 255) / (h - 1);
48 *          for (int x = 0; x < w; x++) {
49 *              int blue = (x * 255) / (w - 1);
50 *              pix[index++] = (255 << 24) | (red << 16) | blue;
51 *          }
52 *      }
53 *      Image img = createImage(new MemoryImageSource(w, h, pix, 0, w));
54 *
55 * }</pre>
56 * The MemoryImageSource is also capable of managing a memory image which
57 * varies over time to allow animation or custom rendering.  Here is an
58 * example showing how to set up the animation source and signal changes
59 * in the data (adapted from the MemoryAnimationSourceDemo by Garth Dickie):
60 * <pre>{@code
61 *
62 *      int pixels[];
63 *      MemoryImageSource source;
64 *
65 *      public void init() {
66 *          int width = 50;
67 *          int height = 50;
68 *          int size = width * height;
69 *          pixels = new int[size];
70 *
71 *          int value = getBackground().getRGB();
72 *          for (int i = 0; i < size; i++) {
73 *              pixels[i] = value;
74 *          }
75 *
76 *          source = new MemoryImageSource(width, height, pixels, 0, width);
77 *          source.setAnimated(true);
78 *          image = createImage(source);
79 *      }
80 *
81 *      public void run() {
82 *          Thread me = Thread.currentThread( );
83 *          me.setPriority(Thread.MIN_PRIORITY);
84 *
85 *          while (true) {
86 *              try {
87 *                  Thread.sleep(10);
88 *              } catch( InterruptedException e ) {
89 *                  return;
90 *              }
91 *
92 *              // Modify the values in the pixels array at (x, y, w, h)
93 *
94 *              // Send the new data to the interested ImageConsumers
95 *              source.newPixels(x, y, w, h);
96 *          }
97 *      }
98 *
99 * }</pre>
100 *
101 * @see ImageProducer
102 *
103 * @author      Jim Graham
104 * @author      Animation capabilities inspired by the
105 *              MemoryAnimationSource class written by Garth Dickie
106 */
107public class MemoryImageSource implements ImageProducer {
108    int width;
109    int height;
110    ColorModel model;
111    Object pixels;
112    int pixeloffset;
113    int pixelscan;
114    Hashtable<?, ?> properties;
115    Vector<ImageConsumer> theConsumers = new Vector<>();
116    boolean animating;
117    boolean fullbuffers;
118
119    /**
120     * Constructs an ImageProducer object which uses an array of bytes
121     * to produce data for an Image object.
122     * @param w the width of the rectangle of pixels
123     * @param h the height of the rectangle of pixels
124     * @param cm the specified {@code ColorModel}
125     * @param pix an array of pixels
126     * @param off the offset into the array of where to store the
127     *        first pixel
128     * @param scan the distance from one row of pixels to the next in
129     *        the array
130     * @see java.awt.Component#createImage
131     */
132    public MemoryImageSource(int w, int h, ColorModel cm,
133                             byte[] pix, int off, int scan) {
134        initialize(w, h, cm, (Object) pix, off, scan, null);
135    }
136
137    /**
138     * Constructs an ImageProducer object which uses an array of bytes
139     * to produce data for an Image object.
140     * @param w the width of the rectangle of pixels
141     * @param h the height of the rectangle of pixels
142     * @param cm the specified {@code ColorModel}
143     * @param pix an array of pixels
144     * @param off the offset into the array of where to store the
145     *        first pixel
146     * @param scan the distance from one row of pixels to the next in
147     *        the array
148     * @param props a list of properties that the {@code ImageProducer}
149     *        uses to process an image
150     * @see java.awt.Component#createImage
151     */
152    public MemoryImageSource(int w, int h, ColorModel cm,
153                             byte[] pix, int off, int scan,
154                             Hashtable<?,?> props)
155    {
156        initialize(w, h, cm, (Object) pix, off, scan, props);
157    }
158
159    /**
160     * Constructs an ImageProducer object which uses an array of integers
161     * to produce data for an Image object.
162     * @param w the width of the rectangle of pixels
163     * @param h the height of the rectangle of pixels
164     * @param cm the specified {@code ColorModel}
165     * @param pix an array of pixels
166     * @param off the offset into the array of where to store the
167     *        first pixel
168     * @param scan the distance from one row of pixels to the next in
169     *        the array
170     * @see java.awt.Component#createImage
171     */
172    public MemoryImageSource(int w, int h, ColorModel cm,
173                             int[] pix, int off, int scan) {
174        initialize(w, h, cm, (Object) pix, off, scan, null);
175    }
176
177    /**
178     * Constructs an ImageProducer object which uses an array of integers
179     * to produce data for an Image object.
180     * @param w the width of the rectangle of pixels
181     * @param h the height of the rectangle of pixels
182     * @param cm the specified {@code ColorModel}
183     * @param pix an array of pixels
184     * @param off the offset into the array of where to store the
185     *        first pixel
186     * @param scan the distance from one row of pixels to the next in
187     *        the array
188     * @param props a list of properties that the {@code ImageProducer}
189     *        uses to process an image
190     * @see java.awt.Component#createImage
191     */
192    public MemoryImageSource(int w, int h, ColorModel cm,
193                             int[] pix, int off, int scan,
194                             Hashtable<?,?> props)
195    {
196        initialize(w, h, cm, (Object) pix, off, scan, props);
197    }
198
199    private void initialize(int w, int h, ColorModel cm,
200                            Object pix, int off, int scan, Hashtable<?,?> props) {
201        width = w;
202        height = h;
203        model = cm;
204        pixels = pix;
205        pixeloffset = off;
206        pixelscan = scan;
207        if (props == null) {
208            props = new Hashtable<>();
209        }
210        properties = props;
211    }
212
213    /**
214     * Constructs an ImageProducer object which uses an array of integers
215     * in the default RGB ColorModel to produce data for an Image object.
216     * @param w the width of the rectangle of pixels
217     * @param h the height of the rectangle of pixels
218     * @param pix an array of pixels
219     * @param off the offset into the array of where to store the
220     *        first pixel
221     * @param scan the distance from one row of pixels to the next in
222     *        the array
223     * @see java.awt.Component#createImage
224     * @see ColorModel#getRGBdefault
225     */
226    public MemoryImageSource(int w, int h, int pix[], int off, int scan) {
227        initialize(w, h, ColorModel.getRGBdefault(),
228                   (Object) pix, off, scan, null);
229    }
230
231    /**
232     * Constructs an ImageProducer object which uses an array of integers
233     * in the default RGB ColorModel to produce data for an Image object.
234     * @param w the width of the rectangle of pixels
235     * @param h the height of the rectangle of pixels
236     * @param pix an array of pixels
237     * @param off the offset into the array of where to store the
238     *        first pixel
239     * @param scan the distance from one row of pixels to the next in
240     *        the array
241     * @param props a list of properties that the {@code ImageProducer}
242     *        uses to process an image
243     * @see java.awt.Component#createImage
244     * @see ColorModel#getRGBdefault
245     */
246    public MemoryImageSource(int w, int h, int pix[], int off, int scan,
247                             Hashtable<?,?> props)
248    {
249        initialize(w, h, ColorModel.getRGBdefault(),
250                   (Object) pix, off, scan, props);
251    }
252
253    /**
254     * Adds an ImageConsumer to the list of consumers interested in
255     * data for this image.
256     * @param ic the specified {@code ImageConsumer}
257     * @throws NullPointerException if the specified
258     *           {@code ImageConsumer} is null
259     * @see ImageConsumer
260     */
261    public synchronized void addConsumer(ImageConsumer ic) {
262        if (theConsumers.contains(ic)) {
263            return;
264        }
265        theConsumers.addElement(ic);
266        try {
267            initConsumer(ic);
268            sendPixels(ic, 0, 0, width, height);
269            if (isConsumer(ic)) {
270                ic.imageComplete(animating
271                                 ? ImageConsumer.SINGLEFRAMEDONE
272                                 : ImageConsumer.STATICIMAGEDONE);
273                if (!animating && isConsumer(ic)) {
274                    ic.imageComplete(ImageConsumer.IMAGEERROR);
275                    removeConsumer(ic);
276                }
277            }
278        } catch (Exception e) {
279            if (isConsumer(ic)) {
280                ic.imageComplete(ImageConsumer.IMAGEERROR);
281            }
282        }
283    }
284
285    /**
286     * Determines if an ImageConsumer is on the list of consumers currently
287     * interested in data for this image.
288     * @param ic the specified {@code ImageConsumer}
289     * @return {@code true} if the {@code ImageConsumer}
290     * is on the list; {@code false} otherwise.
291     * @see ImageConsumer
292     */
293    public synchronized boolean isConsumer(ImageConsumer ic) {
294        return theConsumers.contains(ic);
295    }
296
297    /**
298     * Removes an ImageConsumer from the list of consumers interested in
299     * data for this image.
300     * @param ic the specified {@code ImageConsumer}
301     * @see ImageConsumer
302     */
303    public synchronized void removeConsumer(ImageConsumer ic) {
304        theConsumers.removeElement(ic);
305    }
306
307    /**
308     * Adds an ImageConsumer to the list of consumers interested in
309     * data for this image and immediately starts delivery of the
310     * image data through the ImageConsumer interface.
311     * @param ic the specified {@code ImageConsumer}
312     * image data through the ImageConsumer interface.
313     * @see ImageConsumer
314     */
315    public void startProduction(ImageConsumer ic) {
316        addConsumer(ic);
317    }
318
319    /**
320     * Requests that a given ImageConsumer have the image data delivered
321     * one more time in top-down, left-right order.
322     * @param ic the specified {@code ImageConsumer}
323     * @see ImageConsumer
324     */
325    public void requestTopDownLeftRightResend(ImageConsumer ic) {
326        // Ignored.  The data is either single frame and already in TDLR
327        // format or it is multi-frame and TDLR resends aren't critical.
328    }
329
330    /**
331     * Changes this memory image into a multi-frame animation or a
332     * single-frame static image depending on the animated parameter.
333     * <p>This method should be called immediately after the
334     * MemoryImageSource is constructed and before an image is
335     * created with it to ensure that all ImageConsumers will
336     * receive the correct multi-frame data.  If an ImageConsumer
337     * is added to this ImageProducer before this flag is set then
338     * that ImageConsumer will see only a snapshot of the pixel
339     * data that was available when it connected.
340     * @param animated {@code true} if the image is a
341     *       multi-frame animation
342     */
343    public synchronized void setAnimated(boolean animated) {
344        this.animating = animated;
345        if (!animating) {
346            Enumeration<ImageConsumer> enum_ = theConsumers.elements();
347            while (enum_.hasMoreElements()) {
348                ImageConsumer ic = enum_.nextElement();
349                ic.imageComplete(ImageConsumer.STATICIMAGEDONE);
350                if (isConsumer(ic)) {
351                    ic.imageComplete(ImageConsumer.IMAGEERROR);
352                }
353            }
354            theConsumers.removeAllElements();
355        }
356    }
357
358    /**
359     * Specifies whether this animated memory image should always be
360     * updated by sending the complete buffer of pixels whenever
361     * there is a change.
362     * This flag is ignored if the animation flag is not turned on
363     * through the setAnimated() method.
364     * <p>This method should be called immediately after the
365     * MemoryImageSource is constructed and before an image is
366     * created with it to ensure that all ImageConsumers will
367     * receive the correct pixel delivery hints.
368     * @param fullbuffers {@code true} if the complete pixel
369     *             buffer should always
370     * be sent
371     * @see #setAnimated
372     */
373    public synchronized void setFullBufferUpdates(boolean fullbuffers) {
374        if (this.fullbuffers == fullbuffers) {
375            return;
376        }
377        this.fullbuffers = fullbuffers;
378        if (animating) {
379            Enumeration<ImageConsumer> enum_ = theConsumers.elements();
380            while (enum_.hasMoreElements()) {
381                ImageConsumer ic = enum_.nextElement();
382                ic.setHints(fullbuffers
383                            ? (ImageConsumer.TOPDOWNLEFTRIGHT |
384                               ImageConsumer.COMPLETESCANLINES)
385                            : ImageConsumer.RANDOMPIXELORDER);
386            }
387        }
388    }
389
390    /**
391     * Sends a whole new buffer of pixels to any ImageConsumers that
392     * are currently interested in the data for this image and notify
393     * them that an animation frame is complete.
394     * This method only has effect if the animation flag has been
395     * turned on through the setAnimated() method.
396     * @see #newPixels(int, int, int, int, boolean)
397     * @see ImageConsumer
398     * @see #setAnimated
399     */
400    public void newPixels() {
401        newPixels(0, 0, width, height, true);
402    }
403
404    /**
405     * Sends a rectangular region of the buffer of pixels to any
406     * ImageConsumers that are currently interested in the data for
407     * this image and notify them that an animation frame is complete.
408     * This method only has effect if the animation flag has been
409     * turned on through the setAnimated() method.
410     * If the full buffer update flag was turned on with the
411     * setFullBufferUpdates() method then the rectangle parameters
412     * will be ignored and the entire buffer will always be sent.
413     * @param x the x coordinate of the upper left corner of the rectangle
414     * of pixels to be sent
415     * @param y the y coordinate of the upper left corner of the rectangle
416     * of pixels to be sent
417     * @param w the width of the rectangle of pixels to be sent
418     * @param h the height of the rectangle of pixels to be sent
419     * @see #newPixels(int, int, int, int, boolean)
420     * @see ImageConsumer
421     * @see #setAnimated
422     * @see #setFullBufferUpdates
423     */
424    public synchronized void newPixels(int x, int y, int w, int h) {
425        newPixels(x, y, w, h, true);
426    }
427
428    /**
429     * Sends a rectangular region of the buffer of pixels to any
430     * ImageConsumers that are currently interested in the data for
431     * this image.
432     * If the framenotify parameter is true then the consumers are
433     * also notified that an animation frame is complete.
434     * This method only has effect if the animation flag has been
435     * turned on through the setAnimated() method.
436     * If the full buffer update flag was turned on with the
437     * setFullBufferUpdates() method then the rectangle parameters
438     * will be ignored and the entire buffer will always be sent.
439     * @param x the x coordinate of the upper left corner of the rectangle
440     * of pixels to be sent
441     * @param y the y coordinate of the upper left corner of the rectangle
442     * of pixels to be sent
443     * @param w the width of the rectangle of pixels to be sent
444     * @param h the height of the rectangle of pixels to be sent
445     * @param framenotify {@code true} if the consumers should be sent a
446     * {@link ImageConsumer#SINGLEFRAMEDONE SINGLEFRAMEDONE} notification
447     * @see ImageConsumer
448     * @see #setAnimated
449     * @see #setFullBufferUpdates
450     */
451    public synchronized void newPixels(int x, int y, int w, int h,
452                                       boolean framenotify) {
453        if (animating) {
454            if (fullbuffers) {
455                x = y = 0;
456                w = width;
457                h = height;
458            } else {
459                if (x < 0) {
460                    w += x;
461                    x = 0;
462                }
463                if (x + w > width) {
464                    w = width - x;
465                }
466                if (y < 0) {
467                    h += y;
468                    y = 0;
469                }
470                if (y + h > height) {
471                    h = height - y;
472                }
473            }
474            if ((w <= 0 || h <= 0) && !framenotify) {
475                return;
476            }
477            Enumeration<ImageConsumer> enum_ = theConsumers.elements();
478            while (enum_.hasMoreElements()) {
479                ImageConsumer ic = enum_.nextElement();
480                if (w > 0 && h > 0) {
481                    sendPixels(ic, x, y, w, h);
482                }
483                if (framenotify && isConsumer(ic)) {
484                    ic.imageComplete(ImageConsumer.SINGLEFRAMEDONE);
485                }
486            }
487        }
488    }
489
490    /**
491     * Changes to a new byte array to hold the pixels for this image.
492     * If the animation flag has been turned on through the setAnimated()
493     * method, then the new pixels will be immediately delivered to any
494     * ImageConsumers that are currently interested in the data for
495     * this image.
496     * @param newpix the new pixel array
497     * @param newmodel the specified {@code ColorModel}
498     * @param offset the offset into the array
499     * @param scansize the distance from one row of pixels to the next in
500     * the array
501     * @see #newPixels(int, int, int, int, boolean)
502     * @see #setAnimated
503     */
504    public synchronized void newPixels(byte[] newpix, ColorModel newmodel,
505                                       int offset, int scansize) {
506        this.pixels = newpix;
507        this.model = newmodel;
508        this.pixeloffset = offset;
509        this.pixelscan = scansize;
510        newPixels();
511    }
512
513    /**
514     * Changes to a new int array to hold the pixels for this image.
515     * If the animation flag has been turned on through the setAnimated()
516     * method, then the new pixels will be immediately delivered to any
517     * ImageConsumers that are currently interested in the data for
518     * this image.
519     * @param newpix the new pixel array
520     * @param newmodel the specified {@code ColorModel}
521     * @param offset the offset into the array
522     * @param scansize the distance from one row of pixels to the next in
523     * the array
524     * @see #newPixels(int, int, int, int, boolean)
525     * @see #setAnimated
526     */
527    public synchronized void newPixels(int[] newpix, ColorModel newmodel,
528                                       int offset, int scansize) {
529        this.pixels = newpix;
530        this.model = newmodel;
531        this.pixeloffset = offset;
532        this.pixelscan = scansize;
533        newPixels();
534    }
535
536    private void initConsumer(ImageConsumer ic) {
537        if (isConsumer(ic)) {
538            ic.setDimensions(width, height);
539        }
540        if (isConsumer(ic)) {
541            ic.setProperties(properties);
542        }
543        if (isConsumer(ic)) {
544            ic.setColorModel(model);
545        }
546        if (isConsumer(ic)) {
547            ic.setHints(animating
548                        ? (fullbuffers
549                           ? (ImageConsumer.TOPDOWNLEFTRIGHT |
550                              ImageConsumer.COMPLETESCANLINES)
551                           : ImageConsumer.RANDOMPIXELORDER)
552                        : (ImageConsumer.TOPDOWNLEFTRIGHT |
553                           ImageConsumer.COMPLETESCANLINES |
554                           ImageConsumer.SINGLEPASS |
555                           ImageConsumer.SINGLEFRAME));
556        }
557    }
558
559    private void sendPixels(ImageConsumer ic, int x, int y, int w, int h) {
560        int off = pixeloffset + pixelscan * y + x;
561        if (isConsumer(ic)) {
562            if (pixels instanceof byte[]) {
563                ic.setPixels(x, y, w, h, model,
564                             ((byte[]) pixels), off, pixelscan);
565            } else {
566                ic.setPixels(x, y, w, h, model,
567                             ((int[]) pixels), off, pixelscan);
568            }
569        }
570    }
571}
572