View Javadoc
1   /*
2    * Copyright (c) 1995, 2011, 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 java.awt.image;
27  
28  import java.util.Hashtable;
29  
30  /**
31   * This class implements a filter for the set of interface methods that
32   * are used to deliver data from an ImageProducer to an ImageConsumer.
33   * It is meant to be used in conjunction with a FilteredImageSource
34   * object to produce filtered versions of existing images.  It is a
35   * base class that provides the calls needed to implement a "Null filter"
36   * which has no effect on the data being passed through.  Filters should
37   * subclass this class and override the methods which deal with the
38   * data that needs to be filtered and modify it as necessary.
39   *
40   * @see FilteredImageSource
41   * @see ImageConsumer
42   *
43   * @author      Jim Graham
44   */
45  public class ImageFilter implements ImageConsumer, Cloneable {
46      /**
47       * The consumer of the particular image data stream for which this
48       * instance of the ImageFilter is filtering data.  It is not
49       * initialized during the constructor, but rather during the
50       * getFilterInstance() method call when the FilteredImageSource
51       * is creating a unique instance of this object for a particular
52       * image data stream.
53       * @see #getFilterInstance
54       * @see ImageConsumer
55       */
56      protected ImageConsumer consumer;
57  
58      /**
59       * Returns a unique instance of an ImageFilter object which will
60       * actually perform the filtering for the specified ImageConsumer.
61       * The default implementation just clones this object.
62       * <p>
63       * Note: This method is intended to be called by the ImageProducer
64       * of the Image whose pixels are being filtered.  Developers using
65       * this class to filter pixels from an image should avoid calling
66       * this method directly since that operation could interfere
67       * with the filtering operation.
68       * @param ic the specified <code>ImageConsumer</code>
69       * @return an <code>ImageFilter</code> used to perform the
70       *         filtering for the specified <code>ImageConsumer</code>.
71       */
72      public ImageFilter getFilterInstance(ImageConsumer ic) {
73          ImageFilter instance = (ImageFilter) clone();
74          instance.consumer = ic;
75          return instance;
76      }
77  
78      /**
79       * Filters the information provided in the setDimensions method
80       * of the ImageConsumer interface.
81       * <p>
82       * Note: This method is intended to be called by the ImageProducer
83       * of the Image whose pixels are being filtered.  Developers using
84       * this class to filter pixels from an image should avoid calling
85       * this method directly since that operation could interfere
86       * with the filtering operation.
87       * @see ImageConsumer#setDimensions
88       */
89      public void setDimensions(int width, int height) {
90          consumer.setDimensions(width, height);
91      }
92  
93      /**
94       * Passes the properties from the source object along after adding a
95       * property indicating the stream of filters it has been run through.
96       * <p>
97       * Note: This method is intended to be called by the ImageProducer
98       * of the Image whose pixels are being filtered.  Developers using
99       * this class to filter pixels from an image should avoid calling
100      * this method directly since that operation could interfere
101      * with the filtering operation.
102      *
103      * @param props the properties from the source object
104      * @exception NullPointerException if <code>props</code> is null
105      */
106     public void setProperties(Hashtable<?,?> props) {
107         Hashtable<Object,Object> p = (Hashtable<Object,Object>)props.clone();
108         Object o = p.get("filters");
109         if (o == null) {
110             p.put("filters", toString());
111         } else if (o instanceof String) {
112             p.put("filters", ((String) o)+toString());
113         }
114         consumer.setProperties(p);
115     }
116 
117     /**
118      * Filter the information provided in the setColorModel method
119      * of the ImageConsumer interface.
120      * <p>
121      * Note: This method is intended to be called by the ImageProducer
122      * of the Image whose pixels are being filtered.  Developers using
123      * this class to filter pixels from an image should avoid calling
124      * this method directly since that operation could interfere
125      * with the filtering operation.
126      * @see ImageConsumer#setColorModel
127      */
128     public void setColorModel(ColorModel model) {
129         consumer.setColorModel(model);
130     }
131 
132     /**
133      * Filters the information provided in the setHints method
134      * of the ImageConsumer interface.
135      * <p>
136      * Note: This method is intended to be called by the ImageProducer
137      * of the Image whose pixels are being filtered.  Developers using
138      * this class to filter pixels from an image should avoid calling
139      * this method directly since that operation could interfere
140      * with the filtering operation.
141      * @see ImageConsumer#setHints
142      */
143     public void setHints(int hints) {
144         consumer.setHints(hints);
145     }
146 
147     /**
148      * Filters the information provided in the setPixels method of the
149      * ImageConsumer interface which takes an array of bytes.
150      * <p>
151      * Note: This method is intended to be called by the ImageProducer
152      * of the Image whose pixels are being filtered.  Developers using
153      * this class to filter pixels from an image should avoid calling
154      * this method directly since that operation could interfere
155      * with the filtering operation.
156      * @see ImageConsumer#setPixels
157      */
158     public void setPixels(int x, int y, int w, int h,
159                           ColorModel model, byte pixels[], int off,
160                           int scansize) {
161         consumer.setPixels(x, y, w, h, model, pixels, off, scansize);
162     }
163 
164     /**
165      * Filters the information provided in the setPixels method of the
166      * ImageConsumer interface which takes an array of integers.
167      * <p>
168      * Note: This method is intended to be called by the ImageProducer
169      * of the Image whose pixels are being filtered.  Developers using
170      * this class to filter pixels from an image should avoid calling
171      * this method directly since that operation could interfere
172      * with the filtering operation.
173      * @see ImageConsumer#setPixels
174      */
175     public void setPixels(int x, int y, int w, int h,
176                           ColorModel model, int pixels[], int off,
177                           int scansize) {
178         consumer.setPixels(x, y, w, h, model, pixels, off, scansize);
179     }
180 
181     /**
182      * Filters the information provided in the imageComplete method of
183      * the ImageConsumer interface.
184      * <p>
185      * Note: This method is intended to be called by the ImageProducer
186      * of the Image whose pixels are being filtered.  Developers using
187      * this class to filter pixels from an image should avoid calling
188      * this method directly since that operation could interfere
189      * with the filtering operation.
190      * @see ImageConsumer#imageComplete
191      */
192     public void imageComplete(int status) {
193         consumer.imageComplete(status);
194     }
195 
196     /**
197      * Responds to a request for a TopDownLeftRight (TDLR) ordered resend
198      * of the pixel data from an <code>ImageConsumer</code>.
199      * When an <code>ImageConsumer</code> being fed
200      * by an instance of this <code>ImageFilter</code>
201      * requests a resend of the data in TDLR order,
202      * the <code>FilteredImageSource</code>
203      * invokes this method of the <code>ImageFilter</code>.
204      *
205      * <p>
206      *
207      * An <code>ImageFilter</code> subclass might override this method or not,
208      * depending on if and how it can send data in TDLR order.
209      * Three possibilities exist:
210      *
211      * <ul>
212      * <li>
213      * Do not override this method.
214      * This makes the subclass use the default implementation,
215      * which is to
216      * forward the request
217      * to the indicated <code>ImageProducer</code>
218      * using this filter as the requesting <code>ImageConsumer</code>.
219      * This behavior
220      * is appropriate if the filter can determine
221      * that it will forward the pixels
222      * in TDLR order if its upstream producer object
223      * sends them in TDLR order.
224      *
225      * <li>
226      * Override the method to simply send the data.
227      * This is appropriate if the filter can handle the request itself &#151;
228      * for example,
229      * if the generated pixels have been saved in some sort of buffer.
230      *
231      * <li>
232      * Override the method to do nothing.
233      * This is appropriate
234      * if the filter cannot produce filtered data in TDLR order.
235      * </ul>
236      *
237      * @see ImageProducer#requestTopDownLeftRightResend
238      * @param ip the ImageProducer that is feeding this instance of
239      * the filter - also the ImageProducer that the request should be
240      * forwarded to if necessary
241      * @exception NullPointerException if <code>ip</code> is null
242      */
243     public void resendTopDownLeftRight(ImageProducer ip) {
244         ip.requestTopDownLeftRightResend(this);
245     }
246 
247     /**
248      * Clones this object.
249      */
250     public Object clone() {
251         try {
252             return super.clone();
253         } catch (CloneNotSupportedException e) {
254             // this shouldn't happen, since we are Cloneable
255             throw new InternalError(e);
256         }
257     }
258 }