image.html

J2ME MIDP2.0 final specification

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Creates an immutable image which is decoded from the data stored in
 the specified byte array at the specified offset and length.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;<A HREF="../../../javax/microedition/lcdui/Image.html">Image</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Image.html#createImage(javax.microedition.lcdui.Image)">createImage</A></B>(<A HREF="../../../javax/microedition/lcdui/Image.html">Image</A>&nbsp;source)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Creates an immutable image from a source image.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;<A HREF="../../../javax/microedition/lcdui/Image.html">Image</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Image.html#createImage(javax.microedition.lcdui.Image, int, int, int, int, int)">createImage</A></B>(<A HREF="../../../javax/microedition/lcdui/Image.html">Image</A>&nbsp;image,
            int&nbsp;x,
            int&nbsp;y,
            int&nbsp;width,
            int&nbsp;height,
            int&nbsp;transform)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Creates an immutable image using pixel data from the specified
 region of a source image, transformed as specified.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;<A HREF="../../../javax/microedition/lcdui/Image.html">Image</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Image.html#createImage(java.io.InputStream)">createImage</A></B>(java.io.InputStream&nbsp;stream)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Creates an immutable image from decoded image data obtained from an
 <code>InputStream</code>.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;<A HREF="../../../javax/microedition/lcdui/Image.html">Image</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Image.html#createImage(int, int)">createImage</A></B>(int&nbsp;width,
            int&nbsp;height)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Creates a new, mutable image for off-screen drawing.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;<A HREF="../../../javax/microedition/lcdui/Image.html">Image</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Image.html#createImage(java.lang.String)">createImage</A></B>(String&nbsp;name)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Creates an immutable image from decoded image data obtained from the
 named resource.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>static&nbsp;<A HREF="../../../javax/microedition/lcdui/Image.html">Image</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Image.html#createRGBImage(int[], int, int, boolean)">createRGBImage</A></B>(int[]&nbsp;rgb,
               int&nbsp;width,
               int&nbsp;height,
               boolean&nbsp;processAlpha)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Creates an immutable image from a sequence of ARGB values, specified
 as <code>0xAARRGGBB</code>.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;<A HREF="../../../javax/microedition/lcdui/Graphics.html">Graphics</A></CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Image.html#getGraphics()">getGraphics</A></B>()</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Creates a new <code>Graphics</code> object that renders to this
 image.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;int</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Image.html#getHeight()">getHeight</A></B>()</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Gets the height of the image in pixels.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;void</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Image.html#getRGB(int[], int, int, int, int, int, int)">getRGB</A></B>(int[]&nbsp;rgbData,
       int&nbsp;offset,
       int&nbsp;scanlength,
       int&nbsp;x,
       int&nbsp;y,
       int&nbsp;width,
       int&nbsp;height)</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Obtains ARGB pixel data from the specified region of this image and
 stores it in the provided array of integers.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;int</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Image.html#getWidth()">getWidth</A></B>()</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Gets the width of the image in pixels.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
<CODE>&nbsp;boolean</CODE></FONT></TD>
<TD><CODE><B><A HREF="../../../javax/microedition/lcdui/Image.html#isMutable()">isMutable</A></B>()</CODE>

<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Check if this image is mutable.</TD>
</TR>
</TABLE>
&nbsp;<A NAME="methods_inherited_from_class_java.lang.Object"><!-- --></A>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
<TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor">
<TD><B>Methods inherited from class java.lang.Object</B></TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD><CODE>equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait</CODE></TD>
</TR>
</TABLE>
&nbsp;
<P>

<!-- ============ FIELD DETAIL =========== -->


<!-- ========= CONSTRUCTOR DETAIL ======== -->


<!-- ============ METHOD DETAIL ========== -->

<A NAME="method_detail"><!-- --></A>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="0" WIDTH="100%">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TD COLSPAN=1><FONT SIZE="+2">
<B>Method Detail</B></FONT></TD>
</TR>
</TABLE>

<A NAME="createImage(int, int)"><!-- --></A><H3>
createImage</H3>
<PRE>
public static <A HREF="../../../javax/microedition/lcdui/Image.html">Image</A> <B>createImage</B>(int&nbsp;width,
                                int&nbsp;height)</PRE>
<DL>
<DD>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.<DD><DL>
<DT><B>Parameters:</B><DD><CODE>width</CODE> - the width of the new image, in pixels<DD><CODE>height</CODE> - the height of the new image, in pixels<DT><B>Returns:</B><DD>the created image<DT><B>Throws:</B><DD><CODE>IllegalArgumentException</CODE> - if either <code>width</code> or
 <code>height</code> is zero or less</DL>
</DD>
</DL>
<HR>

<A NAME="createImage(javax.microedition.lcdui.Image)"><!-- --></A><H3>
createImage</H3>
<PRE>
public static <A HREF="../../../javax/microedition/lcdui/Image.html">Image</A> <B>createImage</B>(<A HREF="../../../javax/microedition/lcdui/Image.html">Image</A>&nbsp;source)</PRE>
<DL>
<DD>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.  If an immutable source
 image contains transparency information, this information is copied to
 the new image unchanged.

 <p> This method is useful for placing the contents of mutable images
 into <code>Choice</code> objects.  The application can create
 an off-screen image
 using the
 <A HREF="../../../javax/microedition/lcdui/Image.html#createImage(int, int)"><CODE>createImage(w, h)</CODE></A>
 method, draw into it using a <code>Graphics</code> object
 obtained with the
 <A HREF="../../../javax/microedition/lcdui/Image.html#getGraphics()"><CODE>getGraphics()</CODE></A>
 method, and then create an immutable copy of it with this method.
 The immutable copy may then be placed into <code>Choice</code>
 objects. </p><DD><DL>
<DT><B>Parameters:</B><DD><CODE>source</CODE> - the source image to be copied<DT><B>Returns:</B><DD>the new, immutable image<DT><B>Throws:</B><DD><CODE>NullPointerException</CODE> - if <code>source</code> is <code>null</code></DL>
</DD>
</DL>
<HR>

<A NAME="createImage(java.lang.String)"><!-- --></A><H3>
createImage</H3>
<PRE>
public static <A HREF="../../../javax/microedition/lcdui/Image.html">Image</A> <B>createImage</B>(String&nbsp;name)
                         throws java.io.IOException</PRE>
<DL>
<DD>Creates an immutable image from decoded image data obtained from the
 named resource.  The name parameter is a resource name as defined by
 <CODE>Class.getResourceAsStream(name)</CODE>.  The rules for resolving resource
 names are defined in the
 <a href="../../../java/lang/package-summary.html">
 Application Resource Files</a> section of the
 <code>java.lang</code> package documentation.<DD><DL>
<DT><B>Parameters:</B><DD><CODE>name</CODE> - the name of the resource containing the image data in one of
 the supported image formats<DT><B>Returns:</B><DD>the created image<DT><B>Throws:</B><DD><CODE>NullPointerException</CODE> - if <code>name</code> is <code>null</code><DD><CODE>java.io.IOException</CODE> - if the resource does not exist,
 the data cannot
 be loaded, or the image data cannot be decoded</DL>
</DD>
</DL>
<HR>

<A NAME="createImage(byte[], int, int)"><!-- --></A><H3>
createImage</H3>
<PRE>
public static <A HREF="../../../javax/microedition/lcdui/Image.html">Image</A> <B>createImage</B>(byte[]&nbsp;imageData,
                                int&nbsp;imageOffset,
                                int&nbsp;imageLength)</PRE>
<DL>
<DD>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>The <code>imageoffset</code> and <code>imagelength</code>
 parameters specify a range of
 data within the <code>imageData</code> byte array. The
 <code>imageOffset</code> parameter
 specifies the
 offset into the array of the first data byte to be used. It must
 therefore lie within the range
 <code>[0..(imageData.length-1)]</code>. The
 <code>imageLength</code>
 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
 <code>imageOffset + imageLength &lt; imageData.length</code>. </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><DD><DL>
<DT><B>Parameters:</B><DD><CODE>imageData</CODE> - the array of image data in a supported image format<DD><CODE>imageOffset</CODE> - the offset of the start of the data in the array<DD><CODE>imageLength</CODE> - the length of the data in the array<DT><B>Returns:</B><DD>the created image<DT><B>Throws:</B><DD><CODE>ArrayIndexOutOfBoundsException</CODE> - if <code>imageOffset</code>
 and <code>imageLength</code>
 specify an invalid range<DD><CODE>NullPointerException</CODE> - if <code>imageData</code> is
 <code>null</code><DD><CODE>IllegalArgumentException</CODE> - if <code>imageData</code> is incorrectly
 formatted or otherwise cannot be decoded</DL>
</DD>
</DL>
<HR>

<A NAME="createImage(javax.microedition.lcdui.Image, int, int, int, int, int)"><!-- --></A><H3>
createImage</H3>
<PRE>
public static <A HREF="../../../javax/microedition/lcdui/Image.html">Image</A> <B>createImage</B>(<A HREF="../../../javax/microedition/lcdui/Image.html">Image</A>&nbsp;image,
                                int&nbsp;x,
                                int&nbsp;y,
                                int&nbsp;width,
                                int&nbsp;height,
                                int&nbsp;transform)</PRE>
<DL>
<DD>Creates an immutable image using pixel data from the specified
 region of a source image, transformed as specified.

 <p>The source image may be mutable or immutable.  For immutable source
 images, transparency information, if any, is copied to the new
 image unchanged.</p>

 <p>On some devices, pre-transformed images may render more quickly
 than images that are transformed on the fly using
 <code>drawRegion</code>.
 However, creating such images does consume additional heap space,
 so this technique should be applied only to images whose rendering
 speed is critical.</p>

 <p>The transform function used must be one of the following, as defined
 in the <A HREF="../../../javax/microedition/lcdui/game/Sprite.html"><CODE>Sprite</CODE></A> class:<br>

 <code>Sprite.TRANS_NONE</code> - causes the specified image
 region to be copied unchanged<br>
 <code>Sprite.TRANS_ROT90</code> - causes the specified image
 region to be rotated clockwise by 90 degrees.<br>
 <code>Sprite.TRANS_ROT180</code> - causes the specified image
 region to be rotated clockwise by 180 degrees.<br>
 <code>Sprite.TRANS_ROT270</code> - causes the specified image
 region to be rotated clockwise by 270 degrees.<br>
 <code>Sprite.TRANS_MIRROR</code> - causes the specified image
 region to be reflected about its vertical center.<br>
 <code>Sprite.TRANS_MIRROR_ROT90</code> - causes the specified image
 region to be reflected about its vertical center and then rotated
 clockwise by 90 degrees.<br>
 <code>Sprite.TRANS_MIRROR_ROT180</code> - causes the specified image
 region to be reflected about its vertical center and then rotated
 clockwise by 180 degrees.<br>
 <code>Sprite.TRANS_MIRROR_ROT270</code> - causes the specified image
 region to be reflected about its vertical center and then rotated
 clockwise by 270 degrees.<br></p>

 <p>
 The size of the returned image will be the size of the specified region
 with the transform applied.  For example, if the region is
 <code>100&nbsp;x&nbsp;50</code> pixels and the transform is
 <code>TRANS_ROT90</code>, the
 returned image will be <code>50&nbsp;x&nbsp;100</code> pixels.</p>

 <p><strong>Note:</strong> If all of the following conditions
 are met, this method may
 simply return the source <code>Image</code> without creating a
 new one:</p>
 <ul>
 <li>the source image is immutable;</li>
 <li>the region represents the entire source image; and</li>
 <li>the transform is <code>TRANS_NONE</code>.</li>
 </ul><DD><DL>
<DT><B>Parameters:</B><DD><CODE>image</CODE> - the source image to be copied from<DD><CODE>x</CODE> - the horizontal location of the region to be copied<DD><CODE>y</CODE> - the vertical location of the region to be copied<DD><CODE>width</CODE> - the width of the region to be copied<DD><CODE>height</CODE> - the height of the region to be copied<DD><CODE>transform</CODE> - the transform to be applied to the region<DT><B>Returns:</B><DD>the new, immutable image<DT><B>Throws:</B><DD><CODE>NullPointerException</CODE> - if <code>image</code> is <code>null</code><DD><CODE>IllegalArgumentException</CODE> - if the region to be copied exceeds
 the bounds of the source image<DD><CODE>IllegalArgumentException</CODE> - if either <code>width</code> or
 <code>height</code> is zero or less<DD><CODE>IllegalArgumentException</CODE> - if the <code>transform</code>
 is not valid<DT><B>Since: </B><DD>MIDP 2.0</DD>