/*
 * $RCSfile: BMPImageWriteParam.java,v $
 *
 * 
 * Copyright (c) 2005 Sun Microsystems, Inc. All  Rights Reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met: 
 * 
 * - Redistribution of source code must retain the above copyright 
 *   notice, this  list of conditions and the following disclaimer.
 * 
 * - Redistribution in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in 
 *   the documentation and/or other materials provided with the
 *   distribution.
 * 
 * Neither the name of Sun Microsystems, Inc. or the names of 
 * contributors may be used to endorse or promote products derived 
 * from this software without specific prior written permission.
 * 
 * This software is provided "AS IS," without a warranty of any 
 * kind. ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND 
 * WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, 
 * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY
 * EXCLUDED. SUN MIDROSYSTEMS, INC. ("SUN") AND ITS LICENSORS SHALL 
 * NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE AS A RESULT OF 
 * USING, MODIFYING OR DISTRIBUTING THIS SOFTWARE OR ITS
 * DERIVATIVES. IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR 
 * ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL,
 * CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AND
 * REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR
 * INABILITY TO USE THIS SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGES. 
 * 
 * You acknowledge that this software is not designed or intended for 
 * use in the design, construction, operation or maintenance of any 
 * nuclear facility. 
 *
 * $Revision: 1.2 $
 * $Date: 2006/04/14 21:32:04 $
 * $State: Exp $
 */
package com.github.jaiimageio.plugins.bmp;

import java.util.Locale;

import javax.imageio.ImageWriteParam;

import com.github.jaiimageio.impl.plugins.bmp.BMPConstants;

/**
 * A subclass of <code>ImageWriteParam</code> for encoding images in
 * the BMP format.
 *
 * <p> This class allows for the specification of various parameters
 * while writing a BMP format image file.  By default, the data layout 
 * is bottom-up, such that the pixels are stored in bottom-up order, 
 * the first scanline being stored last.
 *
 * <p>The particular compression scheme to be used can be specified by using
 * the <code>setCompressionType()</code> method with the appropriate type
 * string.  The compression scheme specified will be honored if and only if it
 * is compatible with the type of image being written. If the specified 
 * compression scheme is not compatible with the type of image being written
 * then the <code>IOException</code> will be thrown by the BMP image writer.
 * If the compression type is not set explicitly then <code>getCompressionType()</code>
 * will return <code>null</code>. In this case the BMP image writer will select 
 * a compression type that supports encoding of the given image without loss
 * of the color resolution.
 * <p>The compression type strings and the image type(s) each supports are
 * listed in the following
 * table:
 *
 * <p><table border=1>
 * <caption><b>Compression Types</b></caption>
 * <tr><th>Type String</th> <th>Description</th>  <th>Image Types</th></tr>
 * <tr><td>BI_RGB</td>  <td>Uncompressed RLE</td> <td><= 8-bits/sample</td></tr>
 * <tr><td>BI_RLE8</td> <td>8-bit Run Length Encoding</td> <td><= 8-bits/sample</td></tr>
 * <tr><td>BI_RLE4</td> <td>4-bit Run Length Encoding</td> <td><= 4-bits/sample</td></tr>
 * <tr><td>BI_BITFIELDS</td> <td>Packed data</td> <td> 16 or 32 bits/sample</td></tr>
 * <tr><td>BI_JPEG</td> <td>JPEG encoded</td> <td>grayscale or RGB image</td></tr>
 * </table>
 *
 * <p> When <code>BI_BITFIELDS</code> is used, if the image encoded has a
 * <code>DirectColorModel</code>, the bit mask in the color model will be
 * written into the stream.  Otherwise, only 5-5-5 16-bit image or 8-8-8 
 * 32-bit images are supported.
 *
 */
public class BMPImageWriteParam extends ImageWriteParam {

    // deprecated version constants

    /** 
     * Constant for BMP version 2. 
     *
     * @deprecated
     */
    public static final int VERSION_2 = 0;

    /** 
     * Constant for BMP version 3. 
     *
     * @deprecated
     */
    public static final int VERSION_3 = 1;

    /** 
     * Constant for BMP version 4. 
     *
     * @deprecated
     */
    public static final int VERSION_4 = 2;

    /** 
     * Constant for BMP version 5. 
     *
     * @deprecated
     */
    public static final int VERSION_5 = 3;

    private boolean topDown = false;

    /**
     * Constructs a <code>BMPImageWriteParam</code> set to use a given
     * <code>Locale</code> and with default values for all parameters.
     *
     * @param locale a <code>Locale</code> to be used to localize
     * compression type names and quality descriptions, or
     * <code>null</code>.
     */
    public BMPImageWriteParam(Locale locale) {
        super(locale);

        // Set compression types ("BI_RGB" denotes uncompressed).
        compressionTypes = BMPConstants.compressionTypeNames;

        // Set compression flag.
        canWriteCompressed = true;
        compressionMode = MODE_COPY_FROM_METADATA;
        compressionType = compressionTypes[BMPConstants.BI_RGB];
    }

    /**
     * Constructs an <code>BMPImageWriteParam</code> object with default
     * values for all parameters and a <code>null</code> <code>Locale</code>.
     */
    public BMPImageWriteParam() {
        this(null);
    }

    /**
     * Returns the BMP version to be used.  The default is
     * <code>VERSION_3</code>.
     *
     * @deprecated
     * @return the BMP version number.
     */
    public int getVersion() {
        return VERSION_3;
    }

    /**
     * If set, the data will be written out in a top-down manner, the first
     * scanline being written first.
     *
     * Any compression other than <code>BI_RGB</code> or 
     * <code>BI_BITFIELDS</code> is incompatible with the data being 
     * written in top-down order. Setting the <code>topDown</code> argument
     * to <code>true</code> will be honored only when the compression 
     * type at the time of writing the image is one of the two mentioned
     * above. Otherwise, the <code>topDown</code> setting will be ignored.
     * 
     * @param topDown whether the data are written in top-down order.
     */
    public void setTopDown(boolean topDown) {
        this.topDown = topDown;
    }

    /**
     * Returns the value of the <code>topDown</code> parameter.
     * The default is <code>false</code>.
     *
     * @return whether the data are written in top-down order.
     */
    public boolean isTopDown() {
        return topDown;
    }

    // Override superclass implementation to add a new check that compression 
    // is not being set when image has been specified to be encoded in a top
    // down fashion

    /**
     * Sets the compression type to one of the values indicated by
     * <code>getCompressionTypes</code>.  If a value of
     * <code>null</code> is passed in, any previous setting is
     * removed.
     *
     * <p>The method first invokes
     * {@link javax.imageio.ImageWriteParam.#setCompressionType(String) 
     * <code>setCompressionType()</code>}
     *  with the supplied value of <code>compressionType</code>. Next, 
     * if {@link #isTopDown()} returns <code>true</code> and the
     * value of <code>compressionType</code> is incompatible with top-down
     * order, {@link #setTopDown(boolean)} is invoked with parameter
     * <code>topDown</code> set to <code>false</code>. The image will
     * then be written in bottom-up order with the specified
     * <code>compressionType</code>.</p>
     *
     * @param compressionType one of the <code>String</code>s returned
     * by <code>getCompressionTypes</code>, or <code>null</code> to
     * remove any previous setting.
     *
     * @exception UnsupportedOperationException if the writer does not
     * support compression.
     * @exception IllegalStateException if the compression mode is not
     * <code>MODE_EXPLICIT</code>.
     * @exception UnsupportedOperationException if there are no
     * settable compression types.
     * @exception IllegalArgumentException if
     * <code>compressionType</code> is non-<code>null</code> but is not
     * one of the values returned by <code>getCompressionTypes</code>.
     *
     * @see #isTopDown
     * @see #setTopDown
     * @see #getCompressionTypes
     * @see #getCompressionType
     * @see #unsetCompression
     */
    public void setCompressionType(String compressionType) {
        super.setCompressionType(compressionType);
        if (!(compressionType.equals("BI_RGB")) &&
            !(compressionType.equals("BI_BITFIELDS")) && topDown == true) {
            topDown = false;
        }
    }

}