001: /*
002: * $RCSfile: BMPImageWriteParam.java,v $
003: *
004: *
005: * Copyright (c) 2005 Sun Microsystems, Inc. All Rights Reserved.
006: *
007: * Redistribution and use in source and binary forms, with or without
008: * modification, are permitted provided that the following conditions
009: * are met:
010: *
011: * - Redistribution of source code must retain the above copyright
012: * notice, this list of conditions and the following disclaimer.
013: *
014: * - Redistribution in binary form must reproduce the above copyright
015: * notice, this list of conditions and the following disclaimer in
016: * the documentation and/or other materials provided with the
017: * distribution.
018: *
019: * Neither the name of Sun Microsystems, Inc. or the names of
020: * contributors may be used to endorse or promote products derived
021: * from this software without specific prior written permission.
022: *
023: * This software is provided "AS IS," without a warranty of any
024: * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND
025: * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY,
026: * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY
027: * EXCLUDED. SUN MIDROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL
028: * NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF
029: * USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS
030: * DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR
031: * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
032: * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
033: * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR
034: * INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
035: * POSSIBILITY OF SUCH DAMAGES.
036: *
037: * You acknowledge that this software is not designed or intended for
038: * use in the design, construction, operation or maintenance of any
039: * nuclear facility.
040: *
041: * $Revision: 1.2 $
042: * $Date: 2006/04/14 21:32:04 $
043: * $State: Exp $
044: */
045: package com.sun.media.imageio.plugins.bmp;
046:
047: import java.util.Locale;
048: import javax.imageio.ImageWriteParam;
049:
050: import com.sun.media.imageioimpl.plugins.bmp.BMPConstants;
051:
052: /**
053: * A subclass of <code>ImageWriteParam</code> for encoding images in
054: * the BMP format.
055: *
056: * <p> This class allows for the specification of various parameters
057: * while writing a BMP format image file. By default, the data layout
058: * is bottom-up, such that the pixels are stored in bottom-up order,
059: * the first scanline being stored last.
060: *
061: * <p>The particular compression scheme to be used can be specified by using
062: * the <code>setCompressionType()</code> method with the appropriate type
063: * string. The compression scheme specified will be honored if and only if it
064: * is compatible with the type of image being written. If the specified
065: * compression scheme is not compatible with the type of image being written
066: * then the <code>IOException</code> will be thrown by the BMP image writer.
067: * If the compression type is not set explicitly then <code>getCompressionType()</code>
068: * will return <code>null</code>. In this case the BMP image writer will select
069: * a compression type that supports encoding of the given image without loss
070: * of the color resolution.
071: * <p>The compression type strings and the image type(s) each supports are
072: * listed in the following
073: * table:
074: *
075: * <p><table border=1>
076: * <caption><b>Compression Types</b></caption>
077: * <tr><th>Type String</th> <th>Description</th> <th>Image Types</th></tr>
078: * <tr><td>BI_RGB</td> <td>Uncompressed RLE</td> <td><= 8-bits/sample</td></tr>
079: * <tr><td>BI_RLE8</td> <td>8-bit Run Length Encoding</td> <td><= 8-bits/sample</td></tr>
080: * <tr><td>BI_RLE4</td> <td>4-bit Run Length Encoding</td> <td><= 4-bits/sample</td></tr>
081: * <tr><td>BI_BITFIELDS</td> <td>Packed data</td> <td> 16 or 32 bits/sample</td></tr>
082: * <tr><td>BI_JPEG</td> <td>JPEG encoded</td> <td>grayscale or RGB image</td></tr>
083: * </table>
084: *
085: * <p> When <code>BI_BITFIELDS</code> is used, if the image encoded has a
086: * <code>DirectColorModel</code>, the bit mask in the color model will be
087: * written into the stream. Otherwise, only 5-5-5 16-bit image or 8-8-8
088: * 32-bit images are supported.
089: *
090: */
091: public class BMPImageWriteParam extends ImageWriteParam {
092:
093: // deprecated version constants
094:
095: /**
096: * Constant for BMP version 2.
097: *
098: * @deprecated
099: */
100: public static final int VERSION_2 = 0;
101:
102: /**
103: * Constant for BMP version 3.
104: *
105: * @deprecated
106: */
107: public static final int VERSION_3 = 1;
108:
109: /**
110: * Constant for BMP version 4.
111: *
112: * @deprecated
113: */
114: public static final int VERSION_4 = 2;
115:
116: /**
117: * Constant for BMP version 5.
118: *
119: * @deprecated
120: */
121: public static final int VERSION_5 = 3;
122:
123: private boolean topDown = false;
124:
125: /**
126: * Constructs a <code>BMPImageWriteParam</code> set to use a given
127: * <code>Locale</code> and with default values for all parameters.
128: *
129: * @param locale a <code>Locale</code> to be used to localize
130: * compression type names and quality descriptions, or
131: * <code>null</code>.
132: */
133: public BMPImageWriteParam(Locale locale) {
134: super (locale);
135:
136: // Set compression types ("BI_RGB" denotes uncompressed).
137: compressionTypes = BMPConstants.compressionTypeNames;
138:
139: // Set compression flag.
140: canWriteCompressed = true;
141: compressionMode = MODE_COPY_FROM_METADATA;
142: compressionType = compressionTypes[BMPConstants.BI_RGB];
143: }
144:
145: /**
146: * Constructs an <code>BMPImageWriteParam</code> object with default
147: * values for all parameters and a <code>null</code> <code>Locale</code>.
148: */
149: public BMPImageWriteParam() {
150: this (null);
151: }
152:
153: /**
154: * Returns the BMP version to be used. The default is
155: * <code>VERSION_3</code>.
156: *
157: * @deprecated
158: * @return the BMP version number.
159: */
160: public int getVersion() {
161: return VERSION_3;
162: }
163:
164: /**
165: * If set, the data will be written out in a top-down manner, the first
166: * scanline being written first.
167: *
168: * Any compression other than <code>BI_RGB</code> or
169: * <code>BI_BITFIELDS</code> is incompatible with the data being
170: * written in top-down order. Setting the <code>topDown</code> argument
171: * to <code>true</code> will be honored only when the compression
172: * type at the time of writing the image is one of the two mentioned
173: * above. Otherwise, the <code>topDown</code> setting will be ignored.
174: *
175: * @param topDown whether the data are written in top-down order.
176: */
177: public void setTopDown(boolean topDown) {
178: this .topDown = topDown;
179: }
180:
181: /**
182: * Returns the value of the <code>topDown</code> parameter.
183: * The default is <code>false</code>.
184: *
185: * @return whether the data are written in top-down order.
186: */
187: public boolean isTopDown() {
188: return topDown;
189: }
190:
191: // Override superclass implementation to add a new check that compression
192: // is not being set when image has been specified to be encoded in a top
193: // down fashion
194:
195: /**
196: * Sets the compression type to one of the values indicated by
197: * <code>getCompressionTypes</code>. If a value of
198: * <code>null</code> is passed in, any previous setting is
199: * removed.
200: *
201: * <p>The method first invokes
202: * {@link javax.imageio.ImageWriteParam.#setCompressionType(String)
203: * <code>setCompressionType()</code>}
204: * with the supplied value of <code>compressionType</code>. Next,
205: * if {@link #isTopDown()} returns <code>true</code> and the
206: * value of <code>compressionType</code> is incompatible with top-down
207: * order, {@link #setTopDown(boolean)} is invoked with parameter
208: * <code>topDown</code> set to <code>false</code>. The image will
209: * then be written in bottom-up order with the specified
210: * <code>compressionType</code>.</p>
211: *
212: * @param compressionType one of the <code>String</code>s returned
213: * by <code>getCompressionTypes</code>, or <code>null</code> to
214: * remove any previous setting.
215: *
216: * @exception UnsupportedOperationException if the writer does not
217: * support compression.
218: * @exception IllegalStateException if the compression mode is not
219: * <code>MODE_EXPLICIT</code>.
220: * @exception UnsupportedOperationException if there are no
221: * settable compression types.
222: * @exception IllegalArgumentException if
223: * <code>compressionType</code> is non-<code>null</code> but is not
224: * one of the values returned by <code>getCompressionTypes</code>.
225: *
226: * @see #isTopDown
227: * @see #setTopDown
228: * @see #getCompressionTypes
229: * @see #getCompressionType
230: * @see #unsetCompression
231: */
232: public void setCompressionType(String compressionType) {
233: super .setCompressionType(compressionType);
234: if (!(compressionType.equals("BI_RGB"))
235: && !(compressionType.equals("BI_BITFIELDS"))
236: && topDown == true) {
237: topDown = false;
238: }
239: }
240:
241: }
| 