You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
258 lines
12 KiB
258 lines
12 KiB
/*
|
|
*
|
|
* Copyright (c) 2007, Oracle and/or its affiliates. All rights reserved.
|
|
* ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
|
|
*/
|
|
|
|
/**********************************************************************
|
|
**********************************************************************
|
|
**********************************************************************
|
|
*** COPYRIGHT (c) 1997-1998 Eastman Kodak Company. ***
|
|
*** As an unpublished work pursuant to Title 17 of the United ***
|
|
*** States Code. All rights reserved. ***
|
|
**********************************************************************
|
|
**********************************************************************
|
|
**********************************************************************/
|
|
|
|
package com.sun.image.codec.jpeg;
|
|
|
|
|
|
/**
|
|
* JPEGEncodeParam encapsulates tables and options necessary to
|
|
* control encoding of JPEG data streams. Parameters are either set
|
|
* explicitly by the application for encoding, or read from another
|
|
* JPEG header.<p>
|
|
|
|
* When working with BufferedImages, the codec will attempt to match
|
|
* the encoded JPEG COLOR_ID with the ColorModel in the BufferedImage.
|
|
* This is not always possible (the default mappings are listed
|
|
* below). In cases where unsupported conversions are required (or
|
|
* odd image colorspaces are in use) the user must either convert the
|
|
* image data to a known ColorSpace or encode the data from a raster.
|
|
* When encoding rasters no colorspace adjustments are made, so the
|
|
* user must do any conversions required to get to the encoded
|
|
* COLOR_ID.
|
|
|
|
* The COLOR_ID for the encoded images is used to control the JPEG
|
|
* codec's inital values for Huffman and Quantization Tables as well
|
|
* as subsampling factors. It is also used to determine what color
|
|
* conversion should be performed to obtain the best encoding.<p>
|
|
|
|
* Note: The color ids described herein are simply enumerated values
|
|
* that influence data processing by the JPEG codec. JPEG compression
|
|
* is, by definition, color blind. These values are used as hints when
|
|
* compressing JPEG data. Through these values the JPEG codec can
|
|
* perform some default rotation of data into spaces that will aid in
|
|
* getting better compression ratios.<P>
|
|
|
|
* Example behaviour is described below. Since these mappings are
|
|
* likely to change in the future it is strongly recommended that you
|
|
* make use of the @see JPEGImageEncoder.getDefaultParamBlock calls
|
|
* and check the encodedColorID for your particular BufferedImage.
|
|
|
|
* In extreme cases is may be necessary for the user to convert the
|
|
* image to the desired colorspace, and encode it from a Raster. In
|
|
* this case the API programmer must specify the colorID of the data
|
|
* in the Raster and no color conversion will take place.
|
|
<pre>
|
|
ENCODING:
|
|
|
|
BufferedImage Type/Instance JPEG (Encoded) Color ID
|
|
======================== =======================
|
|
TYPE_GRAY COLOR_ID_GRAYSCALE
|
|
TYPE_RGB COLOR_ID_YCbCr
|
|
TYPE_YCbCr COLOR_ID_YCbCr
|
|
TYPE_YCbCr/CS_PYCC COLOR_ID_PYCC
|
|
TYPE_CMYK COLOR_ID_CMYK
|
|
TYPE_RGB (w/ alpha) COLOR_ID_YCbCrA
|
|
TYPE_YCbCr (w/ alpha) COLOR_ID_YCbCrA
|
|
TYPE_YCbCr/CS_PYCC (w/ alpha) COLOR_ID_PYCCA
|
|
** Any Other ** COLOR_ID_UNKNOWN
|
|
</pre>
|
|
|
|
* When the user wants more control than the BufferedImage conversions
|
|
* provide, the user must encode the data from a Raster. In this case
|
|
* the data undergoes no color conversion at all. It is the user's
|
|
* responsiblity to perform the desired conversions.<P>
|
|
|
|
* If you intend to write a JFIF image (by including the APP0_MARKER)
|
|
* the encoded COLOR_ID must be one of: COLOR_ID_UNKNOWN,
|
|
* COLOR_ID_GRAYSCALE, COLOR_ID_YCbCr, or COLOR_ID_CMYK. In all other
|
|
* instances an ImageformatException will be thrown.<P>
|
|
|
|
* <B>IMPORTANT:</B> an Alpha RGB BufferedImage will not map to a
|
|
* valid JFIF stream, you must strip off the alpha prior to encoding
|
|
* if you want a JFIF file. If the APP0 marker is set and you do not
|
|
* strip off the Alpha, an ImageFormatException will be thrown.
|
|
* <p>
|
|
* Note that the classes in the com.sun.image.codec.jpeg package are not
|
|
* part of the core Java APIs. They are a part of Sun's JDK and JRE
|
|
* distributions. Although other licensees may choose to distribute these
|
|
* classes, developers cannot depend on their availability in non-Sun
|
|
* implementations. We expect that equivalent functionality will eventually
|
|
* be available in a core API or standard extension.
|
|
* <p>
|
|
*/
|
|
|
|
public interface JPEGEncodeParam
|
|
extends Cloneable, JPEGDecodeParam
|
|
{
|
|
public Object clone();
|
|
|
|
/**
|
|
* Set the horizontal subsample factor for the given component.
|
|
* Note that the subsample factor is the number of input pixels
|
|
* that contribute to each output pixel (ussually 2 for YCC).
|
|
* @param component The component being specified.
|
|
* @param subsample The subsampling factor being specified.
|
|
*/
|
|
public void setHorizontalSubsampling(int component,
|
|
int subsample);
|
|
|
|
/**
|
|
* Set the vertical subsample factor for the given component. Note that
|
|
* the subsample factor is the number of input pixels that
|
|
* contribute to each output pixel (ussually 2 for YCC).
|
|
* @param component The component being specified.
|
|
* @param subsample The subsampling factor being specified.
|
|
*/
|
|
public void setVerticalSubsampling(int component,
|
|
int subsample);
|
|
|
|
/**
|
|
* Sets the coefficient quantization tables at index
|
|
* passed. tableNum must range in value from 0 - 3.
|
|
* @param qtable that will be used.
|
|
* @param tableNum the index of the table to be set.
|
|
*/
|
|
public void setQTable( int tableNum, JPEGQTable qTable );
|
|
|
|
/** Sets the DC Huffman coding table at index to the table provided.
|
|
* @param huffTable JPEGHuffmanTable that will be assigned
|
|
* to index tableNum.
|
|
* @param tableNum - the index of the table to be set.
|
|
* @exception IllegalArgumentException - thrown if the tableNum
|
|
* is out of range. Index must range in value from 0 - 3.
|
|
*/
|
|
public void setDCHuffmanTable( int tableNum,
|
|
JPEGHuffmanTable huffTable);
|
|
|
|
/** Sets the AC Huffman coding table at index to the table provided.
|
|
* @param huffTable JPEGHuffmanTable that will be assigned
|
|
* to index tableNum.
|
|
* @param tableNum - the index of the table to be set.
|
|
* @exception IllegalArgumentException - thrown if the tableNum
|
|
* is out of range. Index must range in value from 0 - 3.
|
|
*/
|
|
public void setACHuffmanTable( int tableNum,
|
|
JPEGHuffmanTable huffTable);
|
|
|
|
|
|
/**
|
|
* Sets the mapping between a component and it's DC Huffman Table.
|
|
* @param component The component to set the mapping for
|
|
* @param table The DC Huffman table to use for component
|
|
*/
|
|
public void setDCHuffmanComponentMapping( int component, int table);
|
|
/**
|
|
* Sets the mapping between a component and it's AC Huffman Table.
|
|
* @param component The component to set the mapping for
|
|
* @param table The AC Huffman table to use for component
|
|
*/
|
|
public void setACHuffmanComponentMapping( int component, int table);
|
|
/**
|
|
* Sets the mapping between a component and it's Quantization Table.
|
|
* @param component The component to set the mapping for
|
|
* @param table The Quantization Table to use for component
|
|
*/
|
|
public void setQTableComponentMapping( int component, int table);
|
|
|
|
/**
|
|
* Set the flag indicating the validity of the table information
|
|
* in the ParamBlock. This is used to indicate if tables should
|
|
* be included when encoding.
|
|
*/
|
|
public void setImageInfoValid(boolean flag);
|
|
|
|
/**
|
|
* Set the flag indicating the validity of the image information
|
|
* in the ParamBlock. This is used to indicates if image data
|
|
* should be written when encoding.
|
|
*/
|
|
public void setTableInfoValid(boolean flag);
|
|
|
|
/**
|
|
* Sets the marker data to be written to the output data stream.
|
|
* This removes any existing marker data in the JPEParm object.
|
|
* This can be used to remove the default APP0 marker by calling
|
|
* it with data set to null.
|
|
* @param marker The marker to set the data for.
|
|
* @param data the new set of data to be written.
|
|
*/
|
|
public void setMarkerData(int marker, byte[][] data);
|
|
|
|
/**
|
|
* Appends 'data' to the array of byte[] associated with
|
|
* marker. This will result in additional instance of the marker
|
|
* being written (one for each byte[] in the array.).
|
|
* @param marker The marker to add and instance of.
|
|
* @param data the data to be written.
|
|
*/
|
|
public void addMarkerData(int marker, byte []data);
|
|
|
|
/**
|
|
* Set the MCUs per restart, or 0 for no restart markers.
|
|
* @param restartInterval number MCUs per restart marker.
|
|
*/
|
|
public void setRestartInterval( int restartInterval );
|
|
|
|
|
|
/**
|
|
* Set the pixel size units This value is copied into the APP0
|
|
* marker (if that marker is written). This value isn't used by
|
|
* the JPEG code.
|
|
* @param unit One of the DENSITY_UNIT_* values.
|
|
*/
|
|
public void setDensityUnit( int unit);
|
|
/**
|
|
* Set the horizontal pixel density This value is written into the
|
|
* APP0 marker. It isn't used by the JPEG code.
|
|
* @param density the horizontal pixel density, in units
|
|
* described by @see JPEGParam.getDensityUnit.
|
|
*/
|
|
public void setXDensity( int density );
|
|
/**
|
|
* Set the vertical pixel density. This value is copied into
|
|
* the JFIF APP0 marker. It isn't used by the JPEG code.
|
|
* @param density The verticle pixel density, in units
|
|
* described by @see JPEGParam.getDensityUnit.
|
|
*/
|
|
public void setYDensity( int density );
|
|
|
|
/**
|
|
* This creates new Quantization tables that replace the currently
|
|
* installed Quantization tables. It also updates the Component
|
|
* QTable mapping to the default for the current encoded COLOR_ID.
|
|
|
|
* The Created Quantization table varies from very high
|
|
* compression, very low quality, (0.0) to low compression, very
|
|
* high quality (1.0) based on the quality parameter.<P>
|
|
|
|
* At a quality level of 1.0 the table will be all 1's which will
|
|
* lead to no loss of data due to quantization (however chrominace
|
|
* subsampling, if used, and roundoff error in the DCT will still
|
|
* degrade the image some what).<P>
|
|
|
|
* This is a linear manipulation of the standard Chrominance
|
|
* Q-Table.<P>
|
|
|
|
* <pre>Some guidelines: 0.75 high quality
|
|
* 0.5 medium quality
|
|
* 0.25 low quality
|
|
* </pre>
|
|
* @param quality 0.0-1.0 setting of desired quality level.
|
|
* @param forceBaseline force baseline quantization table
|
|
*/
|
|
public void setQuality(float quality, boolean forceBaseline );
|
|
}
|