image.java

有关j2me的很好的例子可以研究一下

/*
 * @(#)Image.java	1.30 01/07/12
 * Copyright (c) 1999-2001 Sun Microsystems, Inc. All Rights Reserved.
 *
 * This software is the confidential and proprietary information of Sun
 * Microsystems, Inc. ("Confidential Information").  You shall not
 * disclose such Confidential Information and shall use it only in
 * accordance with the terms of the license agreement you entered into
 * with Sun.
 *
 * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
 * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
 * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
 * THIS SOFTWARE OR ITS DERIVATIVES.
 */
package javax.microedition.lcdui;

import java.io.InputStream;
import java.io.IOException;

/**
 * <p> The Image class is used to hold graphical image data. Image
 * objects exist independently of the display device. They exist only in
 * off-screen memory and will not be painted on the display unless an explicit
 * command is issued by the application (such as within the paint() method of
 * a Canvas) or when an Image object is placed within a Form screen or an
 * Alert screen and that screen is made current. </p>
 *
 * <p> Images are either <em>mutable</em> or <em>immutable</em> depending upon
 * how they are created. Immutable images are generally created by loading
 * image data from resource bundles, from files, or from the network. They may
 * not be modified once created. Mutable images are created in off-screen
 * memory. The application may paint into them after having created a Graphics
 * object expressly for this purpose. Images to be placed within Alert, Choice,
 * Form, or ImageItem objects are required to be immutable because the
 * implementation may use them to update the display at any time, without
 * notifying the application.</p>
 * 
 * <p>An immutable
 * image may be created from a mutable image through the use of the {@link
 * #createImage(Image) createImage} method. It is possible to create a
 * mutable copy of an immutable image using a technique similar to the
 * following: </p>
 *
 * <pre>
 *    Image source; // the image to be copied
 *    source = Image.createImage(...);
 *    Image copy = Image.createImage(source.getWidth(), source.getHeight());
 *    Graphics g = copy.getGraphics();
 *    g.drawImage(source, 0, 0, TOP|LEFT);
 * </pre>
 *
 * <p> It is also possible to use this technique to create a copy of a 
 * subrectangle of an image, by altering the width and height parameters of the 
 * createImage() call that creates the destination image and by altering the x 
 * and y parameters of the drawImage() call.</p>
 * 
 * <a name="PNG"></a>
 * <h3>PNG Image Format</h3>
 * 
 * <p>Implementations are required to support images stored in the PNG (Portable
 * Network Graphics) format, version 1.0.</p>
 *
 * <p><b>Note:</b> The remainder of this section consists of a summary of the
 * minimum set of features required for PNG conformance, along with some
 * considerations for MIDP implementors and application developers.  The
 * information about PNG has been condensed from the <em>PNG (Portable Network
 * Graphics) Specification, Version 1.0.</em>  Any discrepancies between this
 * section and the <em>PNG Specification</em> should be resolved in favor of
 * the <em>PNG Specification.</em></p>
 * 
 * <p>All of the 'critical' chunks specified by PNG must be supported. The
 * paragraphs below describe these critical chunks.</p>
 * 
 * <p>The IHDR chunk. MIDP devices must handle the following values in
 * the IHDR chunk:</p>
 * 
 * <ul>
 * <li>All positive values of width and height are supported; however, a
 * very large image may not be readable because of memory constraints.</li>
 * 
 * <li>All color types are supported, although the appearance of the image will
 * be dependent on the capabilities of the device's screen.  Color types that
 * include alpha channel data are supported; however, the implementation may 
 * ignore all alpha channel information and treat all pixels as opaque.</li>
 *
 * <li>All bit depth values for the given color type are supported.</li>
 * 
 * <li>Compression method 0 (deflate) is the only supported compression method.
 * This is the same compression method that is used for jar files, and so the
 * decompression (inflate) code may be shared between the jar decoding and PNG
 * decoding implementations.</li>
 * 
 * <li>The filter method represents a series of encoding schemes that may be
 * used to optimize compression.  The PNG spec currently defines a single
 * filter method (method 0) that is an adaptive filtering scheme with five
 * basic filter types.  Filtering is essential for optimal compression since it
 * allows the deflate algorithm to exploit spatial similarities within the
 * image.  Therefore, MIDP devices must support all five filter types defined
 * by filter method 0.</li>
 *
 * <li> MIDP devices are required to read PNG images that are encoded with
 * either interlace method 0 (None) or interlace method 1 (Adam7).  Image
 * loading in MIDP is synchronous and cannot be overlapped with image
 * rendering, and so there is no advantage for an application to use interlace
 * method 1.  Support for decoding interlaced images is required for
 * compatibility with PNG and for the convenience of developers who may already
 * have interlaced images available.</li>
 *
 * </ul>
 * 
 * <p>The PLTE chunk. Palette-based images must be supported.</p>
 *
 * <p>The IDAT chunk.  Image data may be encoded using any of the 5 filter
 * types defined by filter method 0 (None, Sub, Up, Average, Paeth).</p>
 *
 * <p>The IEND chunk.  This chunk must be found in order for the image to be
 * considered valid.</p>
 *
 * <p>Ancillary chunk support.  PNG defines several 'ancillary' chunks that
 * may be present in a PNG image but are not critical for image decoding.  A
 * MIDP implementation <em>may</em> (but is not required to) support
 * any of these
 * chunks.  The implementation <em>should</em> silently ignore any unsupported
 * ancillary chunks that it encounters.  The currently defined ancillary chunks
 * are:
 * </p>
 * 
 * <PRE>
 *    bKGD cHRM gAMA hIST iCCP iTXt pHYs
 *    sBIT sPLT sRGB tEXt tIME tRNS zTXt </PRE>
 *
 * <h3>Reference</h3>
 * 
 * <p><em>PNG (Portable Network Graphics) Specification, Version 1.0.</em>
 * W3C Recommendation, October 1, 1996. http://www.w3.org/TR/REC-png.html.
 * Also available as RFC 2083, http://www.ietf.org/rfc/rfc2083.txt.</p>
 */
public class Image {
    /**
     * Construct a new, empty Image
     */
    Image() {}

    /**
     * <p> Creates a new, mutable image for off-screen drawing. Every pixel
     * within the newly created image is white.  The width and height of the 
     * image must both be greater than zero. </p>
     * 
     * @param width the width of the new image, in pixels
     * @param height the height of the new image, in pixels
     * @return the created image
     *
     * @throws IllegalArgumentException if either width or height is
     * zero or less
     */
    public static Image createImage(int width, int height) {
        if (width <= 0 || height <= 0) {
            throw new IllegalArgumentException();
        }

        // SYNC NOTE: Not accessing any shared data, no locking necessary
        return new MutableImage(width, height);
    }

    /**
     * <p> Creates an immutable image from a source image.
     * If the source image is mutable, an immutable copy is created and 
     * returned.  If the source image is immutable, the implementation may 
     * simply return it without creating a new image. </p>
     *
     * <p> This method is useful for placing images drawn off-screen into 
     * Alert, Choice, Form, and StringItem objects.  The application can
     * create an off-screen image using the
     * {@link #createImage(int, int) createImage(w, h)}
     * method, draw into it using a Graphics object
     * obtained with the
     * {@link #getGraphics() getGraphics()}
     * method, and then create an immutable copy of it with this method.
     * The immutable copy may then be placed into the Alert, Choice, Form, and 
     * StringItem objects.
     * 
     * @param source the source image to be copied
     * @return the new, immutable image
     *
     * @throws NullPointerException if source is null
     */
    public static Image createImage(Image source) {

        // SYNC NOTE: Not accessing any shared data, no locking necessary
        return new ImmutableImage(source);
    }

    /**
     * Creates an immutable image from decoded image data obtained from the
     * named resource.  The name parameter is a resource name as defined by
     * {@link Class#getResourceAsStream(String)
     * Class.getResourceAsStream(name)}.
     *
     * @param name the name of the resource containing the image data
     * in one of the supported image formats
     * @return the created image
     * @throws NullPointerException if name is null
     * @throws java.io.IOException if the resource does not exist, the
     * data cannot be loaded, or the image data cannot be decoded
     */
    public static Image createImage(java.lang.String name)
	throws java.io.IOException {
        try {

            // SYNC NOTE: Not accessing any shared data, no locking necessary
            return new ImmutableImage(name);
        } catch (IllegalArgumentException e) {
            throw new java.io.IOException();
        }
    }

    /**
     * <p>Creates an immutable image which is decoded from the data stored in
     * the specified byte array at the specified offset and length. The data
     * must be in a self-identifying image file format supported by the
     * implementation, such as <a href="#PNG">PNG</A>.</p>
     *
     * <p>The imageoffset and imagelength parameters specify a range of
     * data within the imageData byte array. The imageOffset parameter
     * specifies the
     * offset into the array of the first data byte to be used. It must
     * therefore lie within the range [0..(imageData.length-1)]. The
     * imageLength
     * parameter specifies the number of data bytes to be used. It must be a
     * positive integer and it must not cause the range to extend beyond the end
     * of the array. That is, it must be true that
     * imageOffset + imageLength <= imageData.length. </p>
     *
     * <p> This method is intended for use when loading an
     * image from a variety of sources, such as from
     * persistent storage or from the network.</p>
     *