package org.libtiff.jai.codec;

import java.awt.Rectangle;
import java.awt.image.RenderedImage;
import java.awt.image.WritableRaster;
import java.io.IOException;

/**
 * The XTIFFTileCodec is the common interface used by all 
 * registered implementations of TIFF data compression.
 * Unlike other file formats, TIFF has no fixed set of
 * data compressions schemes, but allows for new and
 * user-defined compression types.
 *<p>
 * To use a new codec with the XTIFFDirectory you must
 * do the following things:
 * <ul> 
 * <li> register XTIFF methods with JAI through the XTIFFDescriptor
 * <li> implement the methods below; it is recommended to 
 *      use the XTIFFTileCodecImpl class for this purpose, as
 *      it reduces the problem to one of defining the actual
 *      data compression and decompression algorithms. If you
 *      do not support encoding (e.g LZW), be sure the canEncode()
 *      methods returns false.
 * <li> register the implemented code with the XTIFFDirectory,
 *      indicating in the register method all TIFF compression
 *      codes that this codec can handle.
 * </ul>
 * @see XTIFFTileCodecImpl
 */
public interface XTIFFTileCodec {

	/**
	 * Create a codec for encoding data.
	 * @param param the encoding parameter. It is the responsibility
	 * of the codec to initialize itself from this parameter. 
	 */
    public XTIFFTileCodec create(XTIFFEncodeParam param) throws IOException;

	/**
	 * Create a codec for decoding
	 * @param param the decoding parameter. It is the responsibility
	 * of the codec to initialize itself from this parameter. 
	 */
    public XTIFFTileCodec create(XTIFFDecodeParam param) throws IOException;

	/**
	 * Encode some data from RenderedImage, and return the
         * actual number of bytes stored in output buffer.
	 */
    public int encode(RenderedImage im, Rectangle rect, byte[] output); 

	/**
	 * Decode input byte data into a new WritableRaster, using
	 * information from underlying RenderedImage
	 */
    public WritableRaster decode(RenderedImage im, 
		Rectangle rect, byte[] input); 

	/**
	 * Return the associated TIFF compression code
	 */
    public int getCompression();

	/**
	 * Return the largest possible compressed buffer size 
	 * for this image in bytes. This is used by the XTIFFImage
	 * constructor to allocate a decoding buffer.
	 */
    public int getCompressedTileSize(RenderedImage im);

	/**
	 * Register this codec with the XTIFFDirectory.
	 * The method may register itself with multiple 
	 * TIFF compression codes, if it supports more than
	 * one.
	 * @see XTIFFDirectory
	 */
    public void register();
}