EMMA Coverage Report (generated Wed Aug 16 18:51:55 GMT 2006)
[all classes][javax.imageio]

COVERAGE SUMMARY FOR SOURCE FILE [IIOParam.java]

nameclass, %method, %block, %line, %
IIOParam.java100% (1/1)5%   (1/19)13%  (40/299)16%  (13/83)

COVERAGE BREAKDOWN BY CLASS AND METHOD

nameclass, %method, %block, %line, %
     
class IIOParam100% (1/1)5%   (1/19)13%  (40/299)16%  (13/83)
IIOParam (): void 100% (1/1)100% (40/40)100% (13/13)
activateController (): boolean 0%   (0/1)0%   (0/21)0%   (0/5)
getController (): IIOParamController 0%   (0/1)0%   (0/14)0%   (0/2)
getDefaultController (): IIOParamController 0%   (0/1)0%   (0/3)0%   (0/1)
getDestinationOffset (): Point 0%   (0/1)0%   (0/3)0%   (0/1)
getDestinationType (): ImageTypeSpecifier 0%   (0/1)0%   (0/3)0%   (0/1)
getSourceBands (): int [] 0%   (0/1)0%   (0/21)0%   (0/5)
getSourceRegion (): Rectangle 0%   (0/1)0%   (0/3)0%   (0/1)
getSourceXSubsampling (): int 0%   (0/1)0%   (0/3)0%   (0/1)
getSourceYSubsampling (): int 0%   (0/1)0%   (0/3)0%   (0/1)
getSubsamplingXOffset (): int 0%   (0/1)0%   (0/3)0%   (0/1)
getSubsamplingYOffset (): int 0%   (0/1)0%   (0/3)0%   (0/1)
hasController (): boolean 0%   (0/1)0%   (0/7)0%   (0/1)
setController (IIOParamController): void 0%   (0/1)0%   (0/22)0%   (0/6)
setDestinationOffset (Point): void 0%   (0/1)0%   (0/11)0%   (0/4)
setDestinationType (ImageTypeSpecifier): void 0%   (0/1)0%   (0/4)0%   (0/2)
setSourceBands (int []): void 0%   (0/1)0%   (0/15)0%   (0/4)
setSourceRegion (Rectangle): void 0%   (0/1)0%   (0/62)0%   (0/17)
setSourceSubsampling (int, int, int, int): void 0%   (0/1)0%   (0/58)0%   (0/16)

1/* IIOParam.java --
2   Copyright (C) 2004  Free Software Foundation, Inc.
3 
4This file is part of GNU Classpath.
5 
6GNU Classpath is free software; you can redistribute it and/or modify
7it under the terms of the GNU General Public License as published by
8the Free Software Foundation; either version 2, or (at your option)
9any later version.
10 
11GNU Classpath is distributed in the hope that it will be useful, but
12WITHOUT ANY WARRANTY; without even the implied warranty of
13MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14General Public License for more details.
15 
16You should have received a copy of the GNU General Public License
17along with GNU Classpath; see the file COPYING.  If not, write to the
18Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
1902110-1301 USA.
20 
21Linking this library statically or dynamically with other modules is
22making a combined work based on this library.  Thus, the terms and
23conditions of the GNU General Public License cover the whole
24combination.
25 
26As a special exception, the copyright holders of this library give you
27permission to link this library with independent modules to produce an
28executable, regardless of the license terms of these independent
29modules, and to copy and distribute the resulting executable under
30terms of your choice, provided that you also meet, for each linked
31independent module, the terms and conditions of the license of that
32module.  An independent module is a module which is not derived from
33or based on this library.  If you modify this library, you may extend
34this exception to your version of the library, but you are not
35obligated to do so.  If you do not wish to do so, delete this
36exception statement from your version. */
37 
38 
39package javax.imageio;
40 
41import java.awt.Point;
42import java.awt.Rectangle;
43 
44/**
45 * An IIOParam stores parameters used when encoding or decoding image
46 * streams.  ImageReadParam and ImageWriteParam extend this abstract
47 * base class.
48 *
49 * IIOParams allow control over how source pixels converted into
50 * destination pixels.  This conversion can take place between a
51 * stream and in-memory image data, when an image reader is doing the
52 * conversion, or a writer can be doing the conversion from an
53 * in-memory source to a stream destination.
54 *
55 * An image reader can be restricted to only read from a given region;
56 * likewise a writer can be restricted to only write output to a given
57 * region.
58 *
59 * For image readers and writers, IIOParam supports image pixelation
60 * -- where the input image is approximated by the output image using
61 * larger-sized pixel blocks.  For example: FIXME
62 *
63 * IIOParams can control how pixels are combined into larger blocks
64 * using sub-sampling matrices.  For example: FIXME
65 *
66 * They can also control which source bands are read and written; this
67 * example reads the RGBA (red, green, blue, transparency) data from a
68 * PNG image and outputs just the red and transparency bands: FIXME
69 *
70 * @author Thomas Fitzsimmons (fitzsim@redhat.com)
71 * @author Michael Koch (konqueror@gmx.de)
72 */
73public abstract class IIOParam
74{
75  /**
76   * The controller called by this IIOParam to retrieve parameters.
77   */
78  protected IIOParamController controller = null;
79 
80  /**
81   * The default controller called by this IIOParam to retrieve
82   * parameters.
83   */
84  protected IIOParamController defaultController = null;
85 
86  /**
87   * The offset in the destination where the upper-left
88   * decoded/encoded pixel should be located.
89   */
90  protected Point destinationOffset = new Point(0, 0);
91 
92  /**
93   * Sets the output colour type when writing or the destination image
94   * type when reading.
95   */
96  protected ImageTypeSpecifier destinationType = null;
97 
98  /**
99   * An array indicating which source bands will be used or null.
100   */
101  protected int[] sourceBands = null;
102 
103  /**
104   * The source pixel region or null.
105   */
106  protected Rectangle sourceRegion = null;
107 
108  /**
109   * Sample every sourceXSubsampling'th pixel in the source image when
110   * pixelating the destination image in the horizontal direction.
111   */
112  protected int sourceXSubsampling = 1;
113 
114  /**
115   * Sample every sourceYSubsampling'th pixel in the source image when
116   * pixelating the destination image in the vertical direction.
117   */
118  protected int sourceYSubsampling = 1;
119 
120  /**
121   * Start sampling at this horizontal offset within the source region
122   * when pixelating the destination image in the horizontal
123   * direction.
124   */
125  protected int subsamplingXOffset = 0;
126 
127  /**
128   * Start sampling at this vertical offset within the source region
129   * when pixelating the destination image in the vertical direction.
130   */
131  protected int subsamplingYOffset = 0;
132 
133  /**
134   * Indicates whether or not the controller has been explicitly set
135   * to null.
136   */
137  private boolean no_controller = false;
138 
139  /**
140   * Constructs an IIOParam object.
141   */
142  protected IIOParam()
143  {
144  }
145 
146  /**
147   * Activates the parameter controller by calling its activate method
148   * and passing it this IIOParam.  A true return value indicates that
149   * this IIOParam's values are ready for the next read or write
150   * operation.  A return value of false means that this IIOParam's
151   * values have not been affected because the controller operations
152   * were cancelled.
153   *
154   * @return true if parameters were successfully set, false if
155   * parameters were not changed
156   */
157  public boolean activateController()
158  {
159    if (controller == null)
160      {
161        if (defaultController == null || no_controller)
162          return false;
163        else
164          return defaultController.activate (this);
165      }
166    else
167      return controller.activate(this);
168  }
169 
170  /**
171   * Retrieve the currently set controller if one has been set, or the
172   * default controller, or null if the controller has been explicitly
173   * set to null.
174   *
175   * @return the currently used controller or null
176   */  
177  public IIOParamController getController()
178  {
179    return controller == null ?
180      (no_controller ? null : defaultController) : controller;
181  }
182 
183  /**
184   * Retrieve the default controller regardless of whether or not a
185   * non-default controller has been set.  The default controller may
186   * be null.
187   *
188   * @return the default controller or null
189   */
190  public IIOParamController getDefaultController()
191  {
192    return defaultController;
193  }
194 
195  /**
196   * Retrieve the offset in the destination where the upper-left
197   * decoded/encoded pixel should be located. (0, 0) by default.
198   *
199   * @return the destination offset
200   */
201  public Point getDestinationOffset()
202  {
203    return destinationOffset;
204  }
205 
206  /**
207   * Retrieve the currently set image-type specifier or null if none
208   * has been set.
209   *
210   * @return the current image-type specifier or null
211   */
212  public ImageTypeSpecifier getDestinationType()
213  {
214    return destinationType;
215  }
216 
217  /**
218   * Retrieve the current source band values or null if source band
219   * values have not been set.
220   *
221   * The returned array is a copy of this IIOParam's source band
222   * array.
223   *
224   * @return the current set of source band values or null
225   */
226  public int[] getSourceBands()
227  {
228    if (sourceBands == null)
229      return null;
230 
231    int[] sourceBandsCopy = new int[sourceBands.length];
232    System.arraycopy (sourceBands, 0, sourceBandsCopy, 0, sourceBands.length);
233    return sourceBandsCopy;
234  }
235 
236  /**
237   * Retrieve the source rectangle from which pixels should be read or
238   * null if no source region has been set.
239   *
240   * @return the current source region or null
241   */
242  public Rectangle getSourceRegion()
243  {
244    return sourceRegion;
245  }
246 
247  /**
248   * Retrieve the number of pixel columns to advance before taking a
249   * pixel sample.
250   *
251   * @return the horizontal sub-sampling interval
252   */
253  public int getSourceXSubsampling()
254  {
255    return sourceXSubsampling;
256  }
257  
258  /**
259   * Retrieve the number of pixel rows to advance before taking a
260   * pixel sample.
261   *
262   * @return the vertical sub-sampling interval
263   */
264  public int getSourceYSubsampling()
265  {
266    return sourceYSubsampling;
267  }
268 
269  /**
270   * Retrieve the number of pixel columns to advance before taking any
271   * pixel samples.
272   *
273   * @return the horizontal sub-sampling offset
274   */
275  public int getSubsamplingXOffset()
276  {
277    return subsamplingXOffset;
278  }
279 
280  /**
281   * Retrieve the number of pixel rows to advance before taking any
282   * pixel samples.
283   *
284   * @return the vertical sub-sampling offset
285   */
286  public int getSubsamplingYOffset()
287  {
288    return subsamplingYOffset;
289  }
290 
291  /**
292   * Check if a non-null controller is currently available.
293   *
294   * @return true if getController returns a non-null value, false if
295   * getController returns null
296   */
297  public boolean hasController()
298  {
299    return getController() != null;
300  }
301 
302  /**
303   * Sets the controller for this IIOParam.  This is the controller
304   * that will be activated when activateController is called.  The
305   * argument controller overrides this IIOParam's default controller.
306   * If the argument is null then no controller will be set, not even
307   * the default one.  To reset the default controller call
308   * setController(getDefaultController()).
309   *
310   * @param controller the controller to set or null
311   */
312  public void setController(IIOParamController controller)
313  {
314    if (controller == defaultController)
315      {
316        this.controller = null;
317        no_controller = false;
318      }
319    else
320      {
321        no_controller = (controller == null);
322        this.controller = controller;
323      }
324  }
325 
326  /**
327   * Set the destination image type.
328   *
329   * If this value is set on an image reader then its read method will
330   * return a new BufferedImage of the specified destination type.  In
331   * this case any destination image set using setDestination() is
332   * ignored.
333   *
334   * If this is set on an image writer then the destination type
335   * affects only the colour model of the destination image.  The
336   * destination type's SampleModel is ignored.  The destination
337   * type's ColorModel will override the source image's colour model.
338   *
339   * @param destinationType the sample and colour models of the
340   * destination image
341   */
342  public void setDestinationType (ImageTypeSpecifier destinationType)
343  {
344    this.destinationType = destinationType;
345  }
346 
347  /**
348   * Specify the destination pixel offset.  Image writers are only
349   * affected by this setting when ImageWriter.replacePixels is called
350   * in which case the offset is into the region of pixels being
351   * changed.
352   *
353   * @param destinationOffset the offset where pixel writing should
354   * begin
355   */
356  public void setDestinationOffset(Point destinationOffset)
357  {
358    if (destinationOffset == null)
359      throw new IllegalArgumentException("destinationOffset is null");
360 
361    this.destinationOffset = destinationOffset;
362  }
363 
364  /**
365   * Set the indices of the source bands to be used.  Duplicate
366   * indices are not allowed.  A value of null means use all source
367   * bands.  The argument array is copied and stored, so subsequent
368   * updates to it will not be reflected in this IIOParam.
369   *
370   * @param sourceBands the array of source bands to use
371   */
372  public void setSourceBands(int[] sourceBands)
373  {
374    int[] sourceBandsCopy = new int[sourceBands.length];
375    System.arraycopy (sourceBands, 0, sourceBandsCopy, 0, sourceBands.length);
376    this.sourceBands = sourceBandsCopy;
377  }
378 
379  /**
380   * Set the source region from which to read.  The number of pixels
381   * sampled from the source region depends on the source sub-sampling
382   * settings.  If the combination of this sourceRegion and the
383   * current sub-sampling settings would result in no pixels being
384   * sampled then an IllegalStateException will be thrown.
385   *
386   * The source region is specified in the source image coordinate
387   * system which has point (0, 0) at the top-left and increases down
388   * and to the right.  The argument source region is clipped to the
389   * image boundaries at read-time.
390   *
391   * A null argument sets the source region to null meaning that the
392   * whole image should be read.
393   *
394   * @param sourceRegion the rectangular source region
395   *
396   * @exception IllegalArgumentException if sourceRegion has width or
397   * height <= 0 or x or y < 0
398   * @exception IllegalStateException if the given sourceRegion and
399   * the current sampling settings would produce zero samples
400   */
401  public void setSourceRegion(Rectangle sourceRegion)
402  {
403    if (sourceRegion != null
404        && (sourceRegion.x < 0
405            || sourceRegion.y < 0
406            || sourceRegion.width <= 0
407            || sourceRegion.height <= 0))
408      throw new IllegalArgumentException("illegal source region");
409 
410    if (sourceRegion != null)
411      {
412        int num_rows =
413          (sourceRegion.height - subsamplingYOffset + sourceYSubsampling - 1)
414          / sourceYSubsampling;
415 
416        int num_columns =
417          (sourceRegion.width - subsamplingXOffset + sourceXSubsampling - 1)
418          / sourceXSubsampling;
419 
420        if (num_rows <= 0 || num_columns <= 0)
421          throw new IllegalStateException("zero pixels in source region");
422      }
423 
424    this.sourceRegion = sourceRegion;
425  }
426 
427  /**
428   * Set the source sampling intervals and offsets.  Every
429   * sourceXSubsampling'th pixel horizontally and
430   * sourceYSubsampling'th pixel vertically will be sampled.  Sampling
431   * will being a the subsamplingXOffset'th column and the
432   * subsamplingYOffset'th row.
433   *
434   * Horizontally, the number of sampled pixels will be:
435   *
436   * floor((width - subsamplingXOffset + sourceXSubsampling - 1) / sourceXSubsampling)
437   *
438   * Vertically:
439   *
440   * floor((height - subsamplingYOffset + sourceYSubsampling - 1) / sourceYSubsampling)
441   *
442   * If the current source region setting is such that the given
443   * sub-sampling arguments would produce zero pixel samples, an
444   * IllegalStateException is thrown.
445   *
446   * The offset parameters can be used to make source regions overlap
447   * when tiling across an image.  This can eliminate seams and
448   * better-tile images whose width or height is not a multiple of the
449   * sampling interval.
450   *
451   * @param sourceXSubsampling the horizontal sampling interval
452   * @param sourceYSubsampling the vertical sampling interval
453   * @param subsamplingXOffset the horizontal offset of the initial
454   * sample
455   * @param subsamplingYOffset the vertical offset of the initial
456   * sample
457   *
458   * @exception IllegalArgumentException if either subsamplingXOffset
459   * or subsamplingYOffset is < 0
460   * @exception IllegalStateException if the current source region
461   * combined with the given sub-sampling parameters would produce
462   * zero pixel samples
463   */
464  public void setSourceSubsampling(int sourceXSubsampling, int sourceYSubsampling,
465                                   int subsamplingXOffset, int subsamplingYOffset)
466  {
467    if (subsamplingXOffset < 0 || subsamplingYOffset < 0)
468      throw new IllegalArgumentException("subsampling offset < 0");
469 
470    if (sourceRegion != null)
471      {
472        int num_rows =
473          (sourceRegion.height - subsamplingYOffset + sourceYSubsampling - 1)
474          / sourceYSubsampling;
475 
476        int num_columns =
477          (sourceRegion.width - subsamplingXOffset + sourceXSubsampling - 1)
478          / sourceXSubsampling;
479 
480        if (num_rows <= 0 || num_columns <= 0)
481          throw new IllegalStateException("subsampling parameters would"
482                                          + " produce zero pixel samples"
483                                          + " in source region");
484      }
485 
486    this.sourceXSubsampling = sourceXSubsampling;
487    this.sourceYSubsampling = sourceYSubsampling;
488    this.subsamplingXOffset = subsamplingXOffset;
489    this.subsamplingYOffset = subsamplingYOffset;
490  }
491}

[all classes][javax.imageio]
EMMA 2.0.6427 (unsupported private build) (C) Vladimir Roubtsov