File Doc Category Size Date Package
JPEGDecodeParam.java API Doc Java SE 5 API 13690 Fri Aug 26 14:54:40 BST 2005 com.sun.image.codec.jpeg

JPEGDecodeParam

public interface JPEGDecodeParam implements Cloneable

JPEGDecodeParam encapsulates tables and options necessary to control decoding JPEG datastreams. Parameters are either set explicitly by the application for encoding, or read from the JPEG header for decoding. In the case of decoding abbreviated data streams the application may need to set some/all of the values it's self.

When working with BufferedImages (@see JPEGImageDecoder.decodeBufferedImage), the codec will attempt to generate an appropriate ColorModel for the JPEG COLOR_ID. This is not always possible (example mappings are listed below) . In cases where unsupported conversions are required, or unknown encoded COLOR_ID's are in use, the user must request the data as a Raster and perform the transformations themselves. When decoding into a raster (@see JPEGImageDecoder.decodeRaster) no ColorSpace adjustments are made. 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 decompressing JPEG data. Of particular interest is the default conversion from YCbCr to sRGB when decoding buffered Images.

Note: because JPEG is mostly color-blind color fidelity can not be garunteed. This will hopefully be rectified in the near future by the wide spread inclusion of ICC-profiles in the JPEG data stream (as a special marker). The following is an example of the conversions that take place. This is only a guide to the types of conversions that are allowed. This list is likely to change in the future so it is strongly recommended that you check for thrown ImageFormatExceptions and check the actual ColorModel associated with the BufferedImage returned rather than make assumtions.

DECODING:

JPEG (Encoded) Color ID BufferedImage ColorSpace
======================= ========================
COLOR_ID_UNKNOWN ** Invalid **
COLOR_ID_GRAY CS_GRAY
COLOR_ID_RGB CS_sRGB
COLOR_ID_YCbCr CS_sRGB
COLOR_ID_CMYK ** Invalid **
COLOR_ID_PYCC CS_PYCC
COLOR_ID_RGBA CS_sRGB (w/ alpha)
COLOR_ID_YCbCrA CS_sRGB (w/ alpha)
COLOR_ID_RGBA_INVERTED ** Invalid **
COLOR_ID_YCbCrA_INVERTED ** Invalid **
COLOR_ID_PYCCA CS_PYCC (w/ alpha)
COLOR_ID_YCCK ** Invalid **

If the user needs better control over conversion, the user must request the data as a Raster and handle the conversion of the image data themselves.

When decoding JFIF files the encoded COLOR_ID will always be one of: COLOR_ID_UNKNOWN, COLOR_ID_GRAY, COLOR_ID_RGB, COLOR_ID_YCbCr, COLOR_ID_CMYK, or COLOR_ID_YCCK

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.

Fields Summary
public static final int
COLOR_ID_UNKNOWN
Unknown or Undefined Color ID
public static final int
COLOR_ID_GRAY
Monochrome
public static final int
COLOR_ID_RGB
Red, Green, and Blue
public static final int
COLOR_ID_YCbCr
YCbCr
public static final int
COLOR_ID_CMYK
CMYK
public static final int
COLOR_ID_PYCC
PhotoYCC
public static final int
COLOR_ID_RGBA
RGB-Alpha
public static final int
COLOR_ID_YCbCrA
YCbCr-Alpha
public static final int
COLOR_ID_RGBA_INVERTED
RGB-Alpha with R, G, and B inverted.
public static final int
COLOR_ID_YCbCrA_INVERTED
YCbCr-Alpha with Y, Cb, and Cr inverted.
public static final int
COLOR_ID_PYCCA
PhotoYCC-Alpha
public static final int
COLOR_ID_YCCK
YCbCrK
static final int
NUM_COLOR_ID
Number of color ids defined.
static final int
NUM_TABLES
Number of allowed Huffman and Quantization Tables
public static final int
DENSITY_UNIT_ASPECT_RATIO
The X and Y units simply indicate the aspect ratio of the pixels.
public static final int
DENSITY_UNIT_DOTS_INCH
Pixel density is in pixels per inch.
public static final int
DENSITY_UNIT_DOTS_CM
Pixel density is in pixels per centemeter.
static final int
NUM_DENSITY_UNIT
The max known value for DENSITY_UNIT
public static final int
APP0_MARKER
APP0 marker - JFIF info
public static final int
APP1_MARKER
APP1 marker
public static final int
APP2_MARKER
APP2 marker
public static final int
APP3_MARKER
APP3 marker
public static final int
APP4_MARKER
APP4 marker
public static final int
APP5_MARKER
APP5 marker
public static final int
APP6_MARKER
APP6 marker
public static final int
APP7_MARKER
APP7 marker
public static final int
APP8_MARKER
APP8 marker
public static final int
APP9_MARKER
APP9 marker
public static final int
APPA_MARKER
APPA marker
public static final int
APPB_MARKER
APPB marker
public static final int
APPC_MARKER
APPC marker
public static final int
APPD_MARKER
APPD marker
public static final int
APPE_MARKER
APPE marker - Adobe info
public static final int
APPF_MARKER
APPF marker
public static final int
COMMENT_MARKER
Adobe marker indicates presence/need for Adobe marker.
Constructors Summary
Methods Summary
public java.lang.Object clone()
public int getACHuffmanComponentMapping(int component)
Get the number of the AC Huffman table that will be used for a particular component.
param
component The Component of interest.
return
The table number of the AC Huffman table for component.
public JPEGHuffmanTable getACHuffmanTable(int tableNum)
Returns the AC Huffman coding table requested or null if not defined
param
tableNum the index of the table to be returned.
return
Huffman table stored at index tableNum.
public JPEGHuffmanTable getACHuffmanTableForComponent(int component)
Returns the AC Huffman coding table for the requested component.
param
component the image component of interest.
return
Huffman table associated with component
public int getDCHuffmanComponentMapping(int component)
Get the number of the DC Huffman table that will be used for a particular component.
param
component The Component of interest.
return
The table number of the DC Huffman table for component.
public JPEGHuffmanTable getDCHuffmanTable(int tableNum)
Returns the DC Huffman coding table requested or null if not defined
param
tableNum the index of the table to be returned.
return
Huffman table stored at index tableNum.
public JPEGHuffmanTable getDCHuffmanTableForComponent(int component)
Returns the DC Huffman coding table for the requested component.
param
component the image component of interest.
return
Huffman table associated with component
public int getDensityUnit()
Get the code for pixel size units This value is copied from the APP0 marker. It isn't used by the JPEG codec. If the APP0 marker wasn't present then you can not rely on this value.
return
Value indicating the density unit one of the DENSITY_UNIT_* constants.
public int getEncodedColorID()
Returns the JPEG Encoded color id. This is generally speaking only used if you are decoding into Rasters. Note that when decoding into a Raster no color conversion is performed.
return
The value of the JPEG encoded data's color id.
public int getHeight()
Get the image height
return
The height of the image data in pixels.
public int getHorizontalSubsampling(int component)
Return the Horizontal subsampling factor for requested Component. The Subsample factor is the number of input pixels that contribute to each output pixel. This is distinct from the way the JPEG to each output pixel. This is distinct from the way the JPEG standard defines this quantity, because fractional subsampling factors are not allowed, and it was felt
param
component The component of the encoded image to return the subsampling factor for.
return
The subsample factor.
public boolean getMarker(int marker)
Returns true if at least one instance of the marker is present in the Parameter object. For encoding returns true if there is at least one instance of the marker to be written.
param
marker The marker of interest.
public byte[][] getMarkerData(int marker)
Returns a 'byte[][]' associated with the requested marker in the parameter object. Each entry in the 'byte[][]' is the data associated with one instance of the marker (each marker can theoretically appear any number of times in a stream).
param
marker The marker of interest.
return
The 'byte[][]' for this marker or null if none available.
public int getNumComponents()
Returns the number of components for the current encoding COLOR_ID.
return
the number of Components
public JPEGQTable getQTable(int tableNum)
Returns the coefficient quantization tables or NULL if not defined. tableNum must range in value from 0 - 3.
param
tableNum the index of the table to be returned.
return
Quantization table stored at index tableNum.
public int getQTableComponentMapping(int component)
Get the number of the quantization table that will be used for a particular component.
param
component The Component of interest.
return
The table number of the Quantization table for component.
public JPEGQTable getQTableForComponent(int component)
Returns the Quantization table for the requested component.
param
component the image component of interest.
return
Quantization table associated with component
public int getRestartInterval()
Get the MCUs per restart marker.
return
The number of MCUs between restart markers.
public int getVerticalSubsampling(int component)
Return the Vertical subsampling factor for requested Component. The Subsample factor is the number of input pixels that contribute to each output pixel. This is distinct from the way the JPEG to each output pixel. This is distinct from the way the JPEG standard defines this quantity, because fractional subsampling factors are not allowed, and it was felt
param
component The component of the encoded image to return the subsampling factor for.
return
The subsample factor.
public int getWidth()
Get the image width
return
int the width of the image data in pixels.
public int getXDensity()
Get the horizontal pixel density This value is copied from the APP0 marker. It isn't used by the JPEG code. If the APP0 marker wasn't present then you can not rely on this value.
return
The horizontal pixel density, in units described by
see
#getDensityUnit()
public int getYDensity()
Get the vertical pixel density This value is copied into the APP0 marker. It isn't used by the JPEG code. If the APP0 marker wasn't present then you can not rely on this value.
return
The verticle pixel density, in units described by
see
#getDensityUnit()
public boolean isImageInfoValid()
Returns true if the image information in the ParamBlock is currently valid. This indicates if image data was read from the stream for decoding and weather image data should be written when encoding.
public boolean isTableInfoValid()
Returns true if the tables in the ParamBlock are currently valid. This indicates that tables were read from the stream for decoding. When encoding this indicates wether tables should be written to the stream.