Save This Page
1 /*
2 * Copyright 2000-2001 Sun Microsystems, Inc. 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. Sun designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 * CA 95054 USA or visit www.sun.com if you need additional information or
23 * have any questions.
24 */
25
26 package javax.imageio.plugins.jpeg;
27
28 import javax.imageio.ImageReadParam;
29
30 /**
31 * This class adds the ability to set JPEG quantization and Huffman
32 * tables when using the built-in JPEG reader plug-in. An instance of
33 * this class will be returned from the
34 * <code>getDefaultImageReadParam</code> methods of the built-in JPEG
35 * <code>ImageReader</code>.
36 *
37 * <p> The sole purpose of these additions is to allow the
38 * specification of tables for use in decoding abbreviated streams.
39 * The built-in JPEG reader will also accept an ordinary
40 * <code>ImageReadParam</code>, which is sufficient for decoding
41 * non-abbreviated streams.
42 *
43 * <p> While tables for abbreviated streams are often obtained by
44 * first reading another abbreviated stream containing only the
45 * tables, in some applications the tables are fixed ahead of time.
46 * This class allows the tables to be specified directly from client
47 * code. If no tables are specified either in the stream or in a
48 * <code>JPEGImageReadParam</code>, then the stream is presumed to use
49 * the "standard" visually lossless tables. See {@link JPEGQTable
50 * <code>JPEGQTable</code>} and {@link JPEGHuffmanTable
51 * <code>JPEGHuffmanTable</code>} for more information on the default
52 * tables.
53 *
54 * <p> The default <code>JPEGImageReadParam</code> returned by the
55 * <code>getDefaultReadParam</code> method of the builtin JPEG reader
56 * contains no tables. Default tables may be obtained from the table
57 * classes {@link JPEGQTable <code>JPEGQTable</code>} and {@link
58 * JPEGHuffmanTable <code>JPEGHuffmanTable</code>}.
59 *
60 * <p> If a stream does contain tables, the tables given in a
61 * <code>JPEGImageReadParam</code> are ignored. Furthermore, if the
62 * first image in a stream does contain tables and subsequent ones do
63 * not, then the tables given in the first image are used for all the
64 * abbreviated images. Once tables have been read from a stream, they
65 * can be overridden only by tables subsequently read from the same
66 * stream. In order to specify new tables, the {@link
67 * javax.imageio.ImageReader#setInput <code>setInput</code>} method of
68 * the reader must be called to change the stream.
69 *
70 * <p> Note that this class does not provide a means for obtaining the
71 * tables found in a stream. These may be extracted from a stream by
72 * consulting the <code>IIOMetadata</code> object returned by the
73 * reader.
74 *
75 * <p>
76 * For more information about the operation of the built-in JPEG plug-ins,
77 * see the <A HREF="../../metadata/doc-files/jpeg_metadata.html">JPEG
78 * metadata format specification and usage notes</A>.
79 *
80 */
81 public class JPEGImageReadParam extends ImageReadParam {
82
83 private JPEGQTable[] qTables = null;
84 private JPEGHuffmanTable[] DCHuffmanTables = null;
85 private JPEGHuffmanTable[] ACHuffmanTables = null;
86
87 /**
88 * Constructs a <code>JPEGImageReadParam</code>.
89 */
90 public JPEGImageReadParam() {
91 super();
92 }
93
94 /**
95 * Returns <code>true</code> if tables are currently set.
96 *
97 * @return <code>true</code> if tables are present.
98 */
99 public boolean areTablesSet() {
100 return (qTables != null);
101 }
102
103 /**
104 * Sets the quantization and Huffman tables to use in decoding
105 * abbreviated streams. There may be a maximum of 4 tables of
106 * each type. These tables are ignored once tables are
107 * encountered in the stream. All arguments must be
108 * non-<code>null</code>. The two arrays of Huffman tables must
109 * have the same number of elements. The table specifiers in the
110 * frame and scan headers in the stream are assumed to be
111 * equivalent to indices into these arrays. The argument arrays
112 * are copied by this method.
113 *
114 * @param qTables an array of quantization table objects.
115 * @param DCHuffmanTables an array of Huffman table objects.
116 * @param ACHuffmanTables an array of Huffman table objects.
117 *
118 * @exception IllegalArgumentException if any of the arguments
119 * is <code>null</code>, has more than 4 elements, or if the
120 * numbers of DC and AC tables differ.
121 *
122 * @see #unsetDecodeTables
123 */
124 public void setDecodeTables(JPEGQTable[] qTables,
125 JPEGHuffmanTable[] DCHuffmanTables,
126 JPEGHuffmanTable[] ACHuffmanTables) {
127 if ((qTables == null) ||
128 (DCHuffmanTables == null) ||
129 (ACHuffmanTables == null) ||
130 (qTables.length > 4) ||
131 (DCHuffmanTables.length > 4) ||
132 (ACHuffmanTables.length > 4) ||
133 (DCHuffmanTables.length != ACHuffmanTables.length)) {
134 throw new IllegalArgumentException
135 ("Invalid JPEG table arrays");
136 }
137 this.qTables = (JPEGQTable[])qTables.clone();
138 this.DCHuffmanTables = (JPEGHuffmanTable[])DCHuffmanTables.clone();
139 this.ACHuffmanTables = (JPEGHuffmanTable[])ACHuffmanTables.clone();
140 }
141
142 /**
143 * Removes any quantization and Huffman tables that are currently
144 * set.
145 *
146 * @see #setDecodeTables
147 */
148 public void unsetDecodeTables() {
149 this.qTables = null;
150 this.DCHuffmanTables = null;
151 this.ACHuffmanTables = null;
152 }
153
154 /**
155 * Returns a copy of the array of quantization tables set on the
156 * most recent call to <code>setDecodeTables</code>, or
157 * <code>null</code> if tables are not currently set.
158 *
159 * @return an array of <code>JPEGQTable</code> objects, or
160 * <code>null</code>.
161 *
162 * @see #setDecodeTables
163 */
164 public JPEGQTable[] getQTables() {
165 return (qTables != null) ? (JPEGQTable[])qTables.clone() : null;
166 }
167
168 /**
169 * Returns a copy of the array of DC Huffman tables set on the
170 * most recent call to <code>setDecodeTables</code>, or
171 * <code>null</code> if tables are not currently set.
172 *
173 * @return an array of <code>JPEGHuffmanTable</code> objects, or
174 * <code>null</code>.
175 *
176 * @see #setDecodeTables
177 */
178 public JPEGHuffmanTable[] getDCHuffmanTables() {
179 return (DCHuffmanTables != null)
180 ? (JPEGHuffmanTable[])DCHuffmanTables.clone()
181 : null;
182 }
183
184 /**
185 * Returns a copy of the array of AC Huffman tables set on the
186 * most recent call to <code>setDecodeTables</code>, or
187 * <code>null</code> if tables are not currently set.
188 *
189 * @return an array of <code>JPEGHuffmanTable</code> objects, or
190 * <code>null</code>.
191 *
192 * @see #setDecodeTables
193 */
194 public JPEGHuffmanTable[] getACHuffmanTables() {
195 return (ACHuffmanTables != null)
196 ? (JPEGHuffmanTable[])ACHuffmanTables.clone()
197 : null;
198 }
199 }