PNGDecodeParam


1   /*
2   
3      Copyright 2001  The Apache Software Foundation 
4   
5      Licensed under the Apache License, Version 2.0 (the "License");
6      you may not use this file except in compliance with the License.
7      You may obtain a copy of the License at
8   
9          http://www.apache.org/licenses/LICENSE-2.0
10  
11     Unless required by applicable law or agreed to in writing, software
12     distributed under the License is distributed on an "AS IS" BASIS,
13     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14     See the License for the specific language governing permissions and
15     limitations under the License.
16  
17   */
18  package org.apache.batik.ext.awt.image.codec;
19  
20  /**
21   * An instance of <code>ImageDecodeParam</code> for decoding images in
22   * the PNG format.
23   *
24   * <code>PNGDecodeParam</code> allows several aspects of the decoding
25   * process for PNG images to be controlled.  By default, decoding produces
26   * output images with the following properties:
27   *
28   * <p> Images with a bit depth of 8 or less use a
29   * <code>DataBufferByte</code> to hold the pixel data.  16-bit images
30   * use a <code>DataBufferUShort</code>.
31   *
32   * <p> Palette color images and non-transparent grayscale images with
33   * bit depths of 1, 2, or 4 will have a
34   * <code>MultiPixelPackedSampleModel</code> and an
35   * <code>IndexColorModel</code>.  For palette color images, the
36   * <code>ColorModel</code> palette contains the red, green, blue, and
37   * optionally alpha palette information.  For grayscale images, the
38   * palette is used to expand the pixel data to cover the range 0-255.
39   * The pixels are stored packed 8, 4, or 2 to the byte.
40   *
41   * <p> All other images are stored using a
42   * <code>PixelInterleavedSampleModel</code> with each sample of a pixel
43   * occupying its own <code>byte</code> or <code>short</code> within
44   * the <code>DataBuffer</code>.  A <code>ComponentColorModel</code> is
45   * used which simply extracts the red, green, blue, gray, and/or alpha
46   * information from separate <code>DataBuffer</code> entries.
47   *
48   * <p> Five aspects of this process may be altered by means of methods
49   * in this class.
50   *
51   * <p> <code>setSuppressAlpha()</code> prevents an alpha channel
52   * from appearing in the output.
53   *
54   * <p> <code>setExpandPalette()</code> turns palette-color images into
55   * 3-or 4-channel full-color images.
56   *
57   * <p> <code>setOutput8BitGray()</code> causes 1, 2, or 4 bit
58   * grayscale images to be output in 8-bit form, using a
59   * <code>ComponentSampleModel</code> and
60   * <code>ComponentColorModel</code>.
61   *
62   * <p> <code>setDecodingExponent()</code> causes the output image to be
63   * gamma-corrected using a supplied output gamma value.
64   *
65   * <p> <code>setExpandGrayAlpha()</code> causes 2-channel gray/alpha
66   * (GA) images to be output as full-color (GGGA) images, which may
67   * simplify further processing and display.
68   *
69   * <p><b> This class is not a committed part of the JAI API.  It may
70   * be removed or changed in future releases of JAI.</b>
71   */
72  public class PNGDecodeParam implements ImageDecodeParam {
73  
74      /**
75       * Constructs a default instance of <code>PNGDecodeParam</code>.
76       */
77      public PNGDecodeParam() {}
78  
79      private boolean suppressAlpha = false;
80  
81      /**
82       * Returns <code>true</code> if alpha (transparency) will
83       * be prevented from appearing in the output.
84       */
85      public boolean getSuppressAlpha() {
86          return suppressAlpha;
87      }
88  
89      /**
90       * If set, no alpha (transparency) channel will appear in the
91       * output image.
92       *
93       * <p> The default is to allow transparency to appear in the
94       * output image.
95       */
96      public void setSuppressAlpha(boolean suppressAlpha) {
97          this.suppressAlpha = suppressAlpha;
98      }
99  
100     private boolean expandPalette = false;
101 
102     /**
103      * Returns true if palette-color images will be expanded to
104      * produce full-color output.
105      */
106     public boolean getExpandPalette() {
107         return expandPalette;
108     }
109 
110     /**
111      * If set, palette color images (PNG color type 3) will
112      * be decoded into full-color (RGB) output images.  The output
113      * image may have 3 or 4 channels, depending on the presence of
114      * transparency information.
115      *
116      * <p> The default is to output palette images using a single
117      * channel.  The palette information is used to construct the
118      * output image's <code>ColorModel</code>.
119      */
120     public void setExpandPalette(boolean expandPalette) {
121         this.expandPalette = expandPalette;
122     }
123 
124     private boolean output8BitGray = false;
125 
126     /**
127      * Returns the current value of the 8-bit gray output parameter.
128      */
129     public boolean getOutput8BitGray() {
130         return output8BitGray;
131     }
132 
133     /**
134      * If set, grayscale images with a bit depth less than 8
135      * (1, 2, or 4) will be output in 8 bit form.  The output values
136      * will occupy the full 8-bit range.  For example, gray values
137      * 0, 1, 2, and 3 of a 2-bit image will be output as
138      * 0, 85, 170, and 255.
139      *
140      * <p> The decoding of non-grayscale images and grayscale images
141      * with a bit depth of 8 or 16 are unaffected by this setting.
142      *
143      * <p> The default is not to perform expansion.  Grayscale images
144      * with a depth of 1, 2, or 4 bits will be represented using
145      * a <code>MultiPixelPackedSampleModel</code> and an
146      * <code>IndexColorModel</code>.
147      */
148     public void setOutput8BitGray(boolean output8BitGray) {
149         this.output8BitGray = output8BitGray;
150     }
151 
152     private boolean performGammaCorrection = true;
153 
154     /**
155      * Returns <code>true</code> if gamma correction is to be performed
156      * on the image data.  The default is <code>true</code>.
157      *
158      * <p> If gamma correction is to be performed, the
159      * <code>getUserExponent()</code> and
160      * <code>getDisplayExponent()</code> methods are used in addition to
161      * the gamma value stored within the file (or the default value of
162      * 1/2.2 used if no value is found) to produce a single exponent
163      * using the formula:
164      * <pre>
165      * decoding_exponent = user_exponent/(gamma_from_file * display_exponent)
166      * </pre>
167      */
168     public boolean getPerformGammaCorrection() {
169         return performGammaCorrection;
170     }
171 
172     /**
173      * Turns gamma corection of the image data on or off.
174      */
175     public void setPerformGammaCorrection(boolean performGammaCorrection) {
176         this.performGammaCorrection = performGammaCorrection;
177     }
178 
179     private float userExponent = 1.0F;
180 
181     /**
182      * Returns the current value of the user exponent parameter.
183      * By default, the user exponent is equal to 1.0F.
184      */
185     public float getUserExponent() {
186         return userExponent;
187     }
188 
189     /**
190      * Sets the user exponent to a given value.  The exponent
191      * must be positive.  If not, an
192      * <code>IllegalArgumentException</code> will be thrown.
193      *
194      * <p> The output image pixels will be placed through a transformation
195      * of the form:
196      *
197      * <pre>
198      * sample = integer_sample / (2^bitdepth - 1.0)
199      * decoding_exponent = user_exponent/(gamma_from_file * display_exponent)
200      * output = sample ^ decoding_exponent
201      * </pre>
202      *
203      * where <code>gamma_from_file</code> is the gamma of the file
204      * data, as determined by the <code>gAMA</code>, </code>sRGB</code>,
205      * and/or <code>iCCP</code> chunks, and <code>display_exponent</code>
206      * is the exponent of the intrinsic transfer curve of the display,
207      * generally 2.2.
208      *
209      * <p> Input files which do not specify any gamma are assumed to
210      * have a gamma of <code>1/2.2</code>; such images may be displayed
211      * on a CRT with an exponent of 2.2 using the default user
212      * exponent of 1.0.
213      *
214      * <p> The user exponent may be used in order to change the
215      * effective gamma of a file.  If a file has a stored gamma of
216      * X, but the decoder believes that the true file gamma is Y,
217      * setting a user exponent of Y/X will produce the same result
218      * as changing the file gamma.
219      *
220      * <p> This parameter affects the decoding of all image types.
221      *
222      * @throws IllegalArgumentException if <code>userExponent</code> is 
223      * negative.
224      */
225     public void setUserExponent(float userExponent) {
226         if (userExponent <= 0.0F) {
227             throw new IllegalArgumentException  (PropertyUtil.getString("PNGDecodeParam0"));
228         }
229         this.userExponent = userExponent;
230     }
231 
232     private float displayExponent = 2.2F;
233 
234     /**
235      * Returns the current value of the display exponent parameter.
236      * By default, the display exponent is equal to 2.2F.
237      */
238     public float getDisplayExponent() {
239         return displayExponent;
240     }
241 
242     /**
243      * Sets the display exponent to a given value.  The exponent
244      * must be positive.  If not, an
245      * <code>IllegalArgumentException</code> will be thrown.
246      *
247      * <p> The output image pixels will be placed through a transformation
248      * of the form:
249      *
250      * <pre>
251      * sample = integer_sample / (2^bitdepth - 1.0)
252      * decoding_exponent = user_exponent/(gamma_from_file * display_exponent)
253      * output = sample ^ decoding_exponent
254      * </pre>
255      *
256      * where <code>gamma_from_file</code> is the gamma of the file
257      * data, as determined by the <code>gAMA</code>, </code>sRGB</code>,
258      * and/or <code>iCCP</code> chunks, and <code>user_exponent</code>
259      * is an additional user-supplied parameter.
260      *
261      * <p> Input files which do not specify any gamma are assumed to
262      * have a gamma of <code>1/2.2</code>; such images should be
263      * decoding using the default display exponent of 2.2.
264      *
265      * <p> If an image is to be processed further before being displayed,
266      * it may be preferable to set the display exponent to 1.0 in order
267      * to produce a linear output image.
268      *
269      * <p> This parameter affects the decoding of all image types.
270      *
271      * @throws IllegalArgumentException if <code>userExponent</code> is 
272      * negative.
273      */
274     public void setDisplayExponent(float displayExponent) {
275         if (displayExponent <= 0.0F) {
276             throw new IllegalArgumentException  (PropertyUtil.getString("PNGDecodeParam1"));
277         }
278         this.displayExponent = displayExponent;
279     }
280 
281     private boolean expandGrayAlpha = false;
282 
283     /**
284      * Returns the current setting of the gray/alpha expansion.
285      */
286     public boolean getExpandGrayAlpha() {
287         return expandGrayAlpha;
288     }
289 
290     /**
291      * If set, images containing one channel of gray and one channel of
292      * alpha (GA) will be output in a 4-channel format (GGGA).  This
293      * produces output that may be simpler to process and display.
294      *
295      * <p> This setting affects both images of color type 4 (explicit
296      * alpha) and images of color type 0 (grayscale) that contain
297      * transparency information.
298      *
299      * <p> By default, no expansion is performed.
300      */
301     public void setExpandGrayAlpha(boolean expandGrayAlpha) {
302         this.expandGrayAlpha = expandGrayAlpha;
303     }
304 
305     private boolean generateEncodeParam = false;
306 
307     private PNGEncodeParam encodeParam = null;
308 
309     /**
310      * Returns <code>true</code> if an instance of
311      * <code>PNGEncodeParam</code> will be available after an image
312      * has been decoded via the <code>getEncodeParam</code> method.
313      */
314     public boolean getGenerateEncodeParam() {
315         return generateEncodeParam;
316     }
317 
318     /**
319      * If set, an instance of <code>PNGEncodeParam</code> will be
320      * available after an image has been decoded via the
321      * <code>getEncodeParam</code> method that encapsulates information
322      * about the contents of the PNG file.  If not set, this information
323      * will not be recorded and <code>getEncodeParam()</code> will
324      * return <code>null</code>.
325      */
326     public void setGenerateEncodeParam(boolean generateEncodeParam) {
327         this.generateEncodeParam = generateEncodeParam;
328     }
329 
330     /**
331      * If <code>getGenerateEncodeParam()</code> is <code>true</code>,
332      * this method may be called after decoding has completed, and
333      * will return an instance of <code>PNGEncodeParam</code> containing
334      * information about the contents of the PNG file just decoded. 
335      */
336     public PNGEncodeParam getEncodeParam() {
337         return encodeParam;
338     }
339     
340     /**
341      * Sets the current encoder param instance.  This method is
342      * intended to be called by the PNG decoder and will overwrite the
343      * current instance returned by <code>getEncodeParam</code>.
344      */
345     public void setEncodeParam(PNGEncodeParam encodeParam) {
346         this.encodeParam = encodeParam;
347     }
348 }
349
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags