001 /*
002 * Copyright 2000-2001 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package javax.imageio.plugins.jpeg;
027
028 import javax.imageio.ImageReadParam;
029
030 /**
031 * This class adds the ability to set JPEG quantization and Huffman
032 * tables when using the built-in JPEG reader plug-in. An instance of
033 * this class will be returned from the
034 * <code>getDefaultImageReadParam</code> methods of the built-in JPEG
035 * <code>ImageReader</code>.
036 *
037 * <p> The sole purpose of these additions is to allow the
038 * specification of tables for use in decoding abbreviated streams.
039 * The built-in JPEG reader will also accept an ordinary
040 * <code>ImageReadParam</code>, which is sufficient for decoding
041 * non-abbreviated streams.
042 *
043 * <p> While tables for abbreviated streams are often obtained by
044 * first reading another abbreviated stream containing only the
045 * tables, in some applications the tables are fixed ahead of time.
046 * This class allows the tables to be specified directly from client
047 * code. If no tables are specified either in the stream or in a
048 * <code>JPEGImageReadParam</code>, then the stream is presumed to use
049 * the "standard" visually lossless tables. See {@link JPEGQTable
050 * <code>JPEGQTable</code>} and {@link JPEGHuffmanTable
051 * <code>JPEGHuffmanTable</code>} for more information on the default
052 * tables.
053 *
054 * <p> The default <code>JPEGImageReadParam</code> returned by the
055 * <code>getDefaultReadParam</code> method of the builtin JPEG reader
056 * contains no tables. Default tables may be obtained from the table
057 * classes {@link JPEGQTable <code>JPEGQTable</code>} and {@link
058 * JPEGHuffmanTable <code>JPEGHuffmanTable</code>}.
059 *
060 * <p> If a stream does contain tables, the tables given in a
061 * <code>JPEGImageReadParam</code> are ignored. Furthermore, if the
062 * first image in a stream does contain tables and subsequent ones do
063 * not, then the tables given in the first image are used for all the
064 * abbreviated images. Once tables have been read from a stream, they
065 * can be overridden only by tables subsequently read from the same
066 * stream. In order to specify new tables, the {@link
067 * javax.imageio.ImageReader#setInput <code>setInput</code>} method of
068 * the reader must be called to change the stream.
069 *
070 * <p> Note that this class does not provide a means for obtaining the
071 * tables found in a stream. These may be extracted from a stream by
072 * consulting the <code>IIOMetadata</code> object returned by the
073 * reader.
074 *
075 * <p>
076 * For more information about the operation of the built-in JPEG plug-ins,
077 * see the <A HREF="../../metadata/doc-files/jpeg_metadata.html">JPEG
078 * metadata format specification and usage notes</A>.
079 *
080 * @version 0.5
081 */
082 public class JPEGImageReadParam extends ImageReadParam {
083
084 private JPEGQTable[] qTables = null;
085 private JPEGHuffmanTable[] DCHuffmanTables = null;
086 private JPEGHuffmanTable[] ACHuffmanTables = null;
087
088 /**
089 * Constructs a <code>JPEGImageReadParam</code>.
090 */
091 public JPEGImageReadParam() {
092 super ();
093 }
094
095 /**
096 * Returns <code>true</code> if tables are currently set.
097 *
098 * @return <code>true</code> if tables are present.
099 */
100 public boolean areTablesSet() {
101 return (qTables != null);
102 }
103
104 /**
105 * Sets the quantization and Huffman tables to use in decoding
106 * abbreviated streams. There may be a maximum of 4 tables of
107 * each type. These tables are ignored once tables are
108 * encountered in the stream. All arguments must be
109 * non-<code>null</code>. The two arrays of Huffman tables must
110 * have the same number of elements. The table specifiers in the
111 * frame and scan headers in the stream are assumed to be
112 * equivalent to indices into these arrays. The argument arrays
113 * are copied by this method.
114 *
115 * @param qTables an array of quantization table objects.
116 * @param DCHuffmanTables an array of Huffman table objects.
117 * @param ACHuffmanTables an array of Huffman table objects.
118 *
119 * @exception IllegalArgumentException if any of the arguments
120 * is <code>null</code>, has more than 4 elements, or if the
121 * numbers of DC and AC tables differ.
122 *
123 * @see #unsetDecodeTables
124 */
125 public void setDecodeTables(JPEGQTable[] qTables,
126 JPEGHuffmanTable[] DCHuffmanTables,
127 JPEGHuffmanTable[] ACHuffmanTables) {
128 if ((qTables == null) || (DCHuffmanTables == null)
129 || (ACHuffmanTables == null) || (qTables.length > 4)
130 || (DCHuffmanTables.length > 4)
131 || (ACHuffmanTables.length > 4)
132 || (DCHuffmanTables.length != ACHuffmanTables.length)) {
133 throw new IllegalArgumentException(
134 "Invalid JPEG table arrays");
135 }
136 this .qTables = (JPEGQTable[]) qTables.clone();
137 this .DCHuffmanTables = (JPEGHuffmanTable[]) DCHuffmanTables
138 .clone();
139 this .ACHuffmanTables = (JPEGHuffmanTable[]) ACHuffmanTables
140 .clone();
141 }
142
143 /**
144 * Removes any quantization and Huffman tables that are currently
145 * set.
146 *
147 * @see #setDecodeTables
148 */
149 public void unsetDecodeTables() {
150 this .qTables = null;
151 this .DCHuffmanTables = null;
152 this .ACHuffmanTables = null;
153 }
154
155 /**
156 * Returns a copy of the array of quantization tables set on the
157 * most recent call to <code>setDecodeTables</code>, or
158 * <code>null</code> if tables are not currently set.
159 *
160 * @return an array of <code>JPEGQTable</code> objects, or
161 * <code>null</code>.
162 *
163 * @see #setDecodeTables
164 */
165 public JPEGQTable[] getQTables() {
166 return (qTables != null) ? (JPEGQTable[]) qTables.clone()
167 : null;
168 }
169
170 /**
171 * Returns a copy of the array of DC Huffman tables set on the
172 * most recent call to <code>setDecodeTables</code>, or
173 * <code>null</code> if tables are not currently set.
174 *
175 * @return an array of <code>JPEGHuffmanTable</code> objects, or
176 * <code>null</code>.
177 *
178 * @see #setDecodeTables
179 */
180 public JPEGHuffmanTable[] getDCHuffmanTables() {
181 return (DCHuffmanTables != null) ? (JPEGHuffmanTable[]) DCHuffmanTables
182 .clone()
183 : null;
184 }
185
186 /**
187 * Returns a copy of the array of AC Huffman tables set on the
188 * most recent call to <code>setDecodeTables</code>, or
189 * <code>null</code> if tables are not currently set.
190 *
191 * @return an array of <code>JPEGHuffmanTable</code> objects, or
192 * <code>null</code>.
193 *
194 * @see #setDecodeTables
195 */
196 public JPEGHuffmanTable[] getACHuffmanTables() {
197 return (ACHuffmanTables != null) ? (JPEGHuffmanTable[]) ACHuffmanTables
198 .clone()
199 : null;
200 }
201 }
| 