com.sun.image.codec.jpeg
Interface JPEGDecodeParam

All Superinterfaces:

Cloneable

All Known Subinterfaces:

JPEGEncodeParam

public interface JPEGDecodeParam

extends 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.

Field Summary

static int	APP0_MARKER APP0 marker - JFIF info
static int	APP1_MARKER APP1 marker
static int	APP2_MARKER APP2 marker
static int	APP3_MARKER APP3 marker
static int	APP4_MARKER APP4 marker
static int	APP5_MARKER APP5 marker
static int	APP6_MARKER APP6 marker
static int	APP7_MARKER APP7 marker
static int	APP8_MARKER APP8 marker
static int	APP9_MARKER APP9 marker
static int	APPA_MARKER APPA marker
static int	APPB_MARKER APPB marker
static int	APPC_MARKER APPC marker
static int	APPD_MARKER APPD marker
static int	APPE_MARKER APPE marker - Adobe info
static int	APPF_MARKER APPF marker
static int	COLOR_ID_CMYK CMYK
static int	COLOR_ID_GRAY Monochrome
static int	COLOR_ID_PYCC PhotoYCC
static int	COLOR_ID_PYCCA PhotoYCC-Alpha
static int	COLOR_ID_RGB Red, Green, and Blue
static int	COLOR_ID_RGBA RGB-Alpha
static int	COLOR_ID_RGBA_INVERTED RGB-Alpha with R, G, and B inverted.
static int	COLOR_ID_UNKNOWN Unknown or Undefined Color ID
static int	COLOR_ID_YCbCr YCbCr
static int	COLOR_ID_YCbCrA YCbCr-Alpha
static int	COLOR_ID_YCbCrA_INVERTED YCbCr-Alpha with Y, Cb, and Cr inverted.
static int	COLOR_ID_YCCK YCbCrK
static int	COMMENT_MARKER Adobe marker indicates presence/need for Adobe marker.
static int	DENSITY_UNIT_ASPECT_RATIO The X and Y units simply indicate the aspect ratio of the pixels.
static int	DENSITY_UNIT_DOTS_CM Pixel density is in pixels per centemeter.
static int	DENSITY_UNIT_DOTS_INCH Pixel density is in pixels per inch.
static int	NUM_COLOR_ID Number of color ids defined.
static int	NUM_DENSITY_UNIT The max known value for DENSITY_UNIT
static int	NUM_TABLES Number of allowed Huffman and Quantization Tables

Method Summary

Object	clone()
int	getACHuffmanComponentMapping(int component) Get the number of the AC Huffman table that will be used for a particular component.
JPEGHuffmanTable	getACHuffmanTable(int tableNum) Returns the AC Huffman coding table requested or null if not defined
JPEGHuffmanTable	getACHuffmanTableForComponent(int component) Returns the AC Huffman coding table for the requested component.
int	getDCHuffmanComponentMapping(int component) Get the number of the DC Huffman table that will be used for a particular component.
JPEGHuffmanTable	getDCHuffmanTable(int tableNum) Returns the DC Huffman coding table requested or null if not defined
JPEGHuffmanTable	getDCHuffmanTableForComponent(int component) Returns the DC Huffman coding table for the requested component.
int	getDensityUnit() Get the code for pixel size units This value is copied from the APP0 marker.
int	getEncodedColorID() Returns the JPEG Encoded color id.
int	getHeight() Get the image height
int	getHorizontalSubsampling(int component) Return the Horizontal subsampling factor for requested Component.
boolean	getMarker(int marker) Returns true if at least one instance of the marker is present in the Parameter object.
byte[][]	getMarkerData(int marker) Returns a 'byte[][]' associated with the requested marker in the parameter object.
int	getNumComponents() Returns the number of components for the current encoding COLOR_ID.
JPEGQTable	getQTable(int tableNum) Returns the coefficient quantization tables or NULL if not defined.
int	getQTableComponentMapping(int component) Get the number of the quantization table that will be used for a particular component.
JPEGQTable	getQTableForComponent(int component) Returns the Quantization table for the requested component.
int	getRestartInterval() Get the MCUs per restart marker.
int	getVerticalSubsampling(int component) Return the Vertical subsampling factor for requested Component.
int	getWidth() Get the image width
int	getXDensity() Get the horizontal pixel density This value is copied from the APP0 marker.
int	getYDensity() Get the vertical pixel density This value is copied into the APP0 marker.
boolean	isImageInfoValid() Returns true if the image information in the ParamBlock is currently valid.
boolean	isTableInfoValid() Returns true if the tables in the ParamBlock are currently valid.

Field Detail

COLOR_ID_UNKNOWN

public static final int COLOR_ID_UNKNOWN

Unknown or Undefined Color ID

COLOR_ID_GRAY

public static final int COLOR_ID_GRAY

Monochrome

COLOR_ID_RGB

public static final int COLOR_ID_RGB

Red, Green, and Blue

COLOR_ID_YCbCr

public static final int COLOR_ID_YCbCr

YCbCr

COLOR_ID_CMYK

public static final int COLOR_ID_CMYK

CMYK

COLOR_ID_PYCC

public static final int COLOR_ID_PYCC

PhotoYCC

COLOR_ID_RGBA

public static final int COLOR_ID_RGBA

RGB-Alpha

COLOR_ID_YCbCrA

public static final int COLOR_ID_YCbCrA

YCbCr-Alpha

COLOR_ID_RGBA_INVERTED

public static final int COLOR_ID_RGBA_INVERTED

RGB-Alpha with R, G, and B inverted.

COLOR_ID_YCbCrA_INVERTED

public static final int COLOR_ID_YCbCrA_INVERTED

YCbCr-Alpha with Y, Cb, and Cr inverted.

COLOR_ID_PYCCA

public static final int COLOR_ID_PYCCA

PhotoYCC-Alpha

COLOR_ID_YCCK

public static final int COLOR_ID_YCCK

YCbCrK

NUM_COLOR_ID

public static final int NUM_COLOR_ID

Number of color ids defined.

NUM_TABLES

public static final int NUM_TABLES

Number of allowed Huffman and Quantization Tables

DENSITY_UNIT_ASPECT_RATIO

public static final int DENSITY_UNIT_ASPECT_RATIO

The X and Y units simply indicate the aspect ratio of the pixels.

DENSITY_UNIT_DOTS_INCH

public static final int DENSITY_UNIT_DOTS_INCH

Pixel density is in pixels per inch.

DENSITY_UNIT_DOTS_CM

public static final int DENSITY_UNIT_DOTS_CM

Pixel density is in pixels per centemeter.

NUM_DENSITY_UNIT

public static final int NUM_DENSITY_UNIT

The max known value for DENSITY_UNIT

APP0_MARKER

public static final int APP0_MARKER

APP0 marker - JFIF info

APP1_MARKER

public static final int APP1_MARKER

APP1 marker

APP2_MARKER

public static final int APP2_MARKER

APP2 marker

APP3_MARKER

public static final int APP3_MARKER

APP3 marker

APP4_MARKER

public static final int APP4_MARKER

APP4 marker

APP5_MARKER

public static final int APP5_MARKER

APP5 marker

APP6_MARKER

public static final int APP6_MARKER

APP6 marker

APP7_MARKER

public static final int APP7_MARKER

APP7 marker

APP8_MARKER

public static final int APP8_MARKER

APP8 marker

APP9_MARKER

public static final int APP9_MARKER

APP9 marker

APPA_MARKER

public static final int APPA_MARKER

APPA marker

APPB_MARKER

public static final int APPB_MARKER

APPB marker

APPC_MARKER

public static final int APPC_MARKER

APPC marker

APPD_MARKER

public static final int APPD_MARKER

APPD marker

APPE_MARKER

public static final int APPE_MARKER

APPE marker - Adobe info

APPF_MARKER

public static final int APPF_MARKER

APPF marker

COMMENT_MARKER

public static final int COMMENT_MARKER

Adobe marker indicates presence/need for Adobe marker.

Method Detail

clone

public Object clone()

Overrides:

clone in class Object

getWidth

public int getWidth()

Get the image width

Returns:

int the width of the image data in pixels.

getHeight

public int getHeight()

Get the image height

Returns:

The height of the image data in pixels.

getHorizontalSubsampling

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

Parameters:

component - The component of the encoded image to return the subsampling factor for.

Returns:

The subsample factor.

getVerticalSubsampling

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

Parameters:

component - The component of the encoded image to return the subsampling factor for.

Returns:

The subsample factor.

getQTable

public JPEGQTable getQTable(int tableNum)

Returns the coefficient quantization tables or NULL if not defined. tableNum must range in value from 0 - 3.

Parameters:

tableNum - the index of the table to be returned.

Returns:

Quantization table stored at index tableNum.

getQTableForComponent

public JPEGQTable getQTableForComponent(int component)

Returns the Quantization table for the requested component.

Parameters:

component - the image component of interest.

Returns:

Quantization table associated with component

getDCHuffmanTable

public JPEGHuffmanTable getDCHuffmanTable(int tableNum)

Returns the DC Huffman coding table requested or null if not defined

Parameters:

tableNum - the index of the table to be returned.

Returns:

Huffman table stored at index tableNum.

getDCHuffmanTableForComponent

public JPEGHuffmanTable getDCHuffmanTableForComponent(int component)

Returns the DC Huffman coding table for the requested component.

Parameters:

component - the image component of interest.

Returns:

Huffman table associated with component

getACHuffmanTable

public JPEGHuffmanTable getACHuffmanTable(int tableNum)

Returns the AC Huffman coding table requested or null if not defined

Parameters:

tableNum - the index of the table to be returned.

Returns:

Huffman table stored at index tableNum.

getACHuffmanTableForComponent

public JPEGHuffmanTable getACHuffmanTableForComponent(int component)

Returns the AC Huffman coding table for the requested component.

Parameters:

component - the image component of interest.

Returns:

Huffman table associated with component

getDCHuffmanComponentMapping

public int getDCHuffmanComponentMapping(int component)

Get the number of the DC Huffman table that will be used for a particular component.

Parameters:

component - The Component of interest.

Returns:

The table number of the DC Huffman table for component.

getACHuffmanComponentMapping

public int getACHuffmanComponentMapping(int component)

Get the number of the AC Huffman table that will be used for a particular component.

Parameters:

component - The Component of interest.

Returns:

The table number of the AC Huffman table for component.

getQTableComponentMapping

public int getQTableComponentMapping(int component)

Get the number of the quantization table that will be used for a particular component.

Parameters:

component - The Component of interest.

Returns:

The table number of the Quantization table for component.

isImageInfoValid

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.

isTableInfoValid

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.

getMarker

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.

Parameters:

marker - The marker of interest.

getMarkerData

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).

Parameters:

marker - The marker of interest.

Returns:

The 'byte[][]' for this marker or null if none available.

getEncodedColorID

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.

Returns:

The value of the JPEG encoded data's color id.

getNumComponents

public int getNumComponents()

Returns the number of components for the current encoding COLOR_ID.

Returns:

the number of Components

getRestartInterval

public int getRestartInterval()

Get the MCUs per restart marker.

Returns:

The number of MCUs between restart markers.

getDensityUnit

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.

Returns:

Value indicating the density unit one of the DENSITY_UNIT_* constants.

getXDensity

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.

Returns:

The horizontal pixel density, in units described by

See Also:

JPEGDecodeParam.getDensityUnit.

getYDensity

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.

Returns:

The verticle pixel density, in units described by

See Also:

JPEGDecodeParam.getDensityUnit.