001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package javax.microedition.lcdui;
028:
029: import java.io.InputStream;
030: import java.io.IOException;
031:
032: /**
033: * Creates ImageDate that is based on platform decoder and storage.
034: */
035: interface AbstractImageDataFactory {
036:
037: /**
038: * Creates a new, mutable image data for off-screen drawing. Every pixel
039: * within the newly created image is white. The width and height of the
040: * image must both be greater than zero.
041: *
042: * @param width the width of the new image, in pixels
043: * @param height the height of the new image, in pixels
044: * @return the created image data
045: */
046: ImageData createOffScreenImageData(int width, int height);
047:
048: /**
049: * Creates an immutable image data from a source mutable image data.
050: *
051: * <p> This method is useful for placing the contents of mutable images
052: * into <code>Choice</code> objects. The application can create
053: * an off-screen image
054: * using the
055: * {@link #createImage(int, int) createImage(w, h)}
056: * method, draw into it using a <code>Graphics</code> object
057: * obtained with the
058: * {@link #getGraphics() getGraphics()}
059: * method, and then create an immutable copy of it with this method.
060: * The immutable copy may then be placed into <code>Choice</code>
061: * objects. </p>
062: *
063: * @param mutableSource the source mutable image data to be copied
064: * @return the new immutable image data
065: */
066: ImageData createImmutableCopy(ImageData mutableSource);
067:
068: /**
069: * Creates an immutable image data from decoded image data obtained
070: * from the
071: * named resource. The name parameter is a resource name as defined by
072: * {@link Class#getResourceAsStream(String)
073: * Class.getResourceAsStream(name)}. The rules for resolving resource
074: * names are defined in the
075: * <a href="../../../java/lang/package-summary.html">
076: * Application Resource Files</a> section of the
077: * <code>java.lang</code> package documentation.
078: *
079: * @param name the name of the resource containing the image data in one of
080: * the supported image formats
081: * @return the created image data
082: * @throws java.io.IOException if the resource does not exist,
083: * the data cannot be loaded, or the image data cannot be decoded
084: */
085: ImageData createResourceImageData(String name) throws IOException;
086:
087: /**
088: * Creates an immutable image data which is decoded from the data stored in
089: * the specified byte array at the specified offset and length. The data
090: * must be in a self-identifying image file format supported by the
091: * implementation, such as <a href="#PNG">PNG</A>.
092: *
093: * <p>The <code>imageoffset</code> and <code>imagelength</code>
094: * parameters specify a range of
095: * data within the <code>imageData</code> byte array. The
096: * <code>imageOffset</code> parameter
097: * specifies the
098: * offset into the array of the first data byte to be used. It must
099: * therefore lie within the range
100: * <code>[0..(imageData.length-1)]</code>. The
101: * <code>imageLength</code>
102: * parameter specifies the number of data bytes to be used. It must be a
103: * positive integer and it must not cause the range to extend beyond
104: * the end
105: * of the array. That is, it must be true that
106: * <code>imageOffset + imageLength < imageData.length</code>. </p>
107: *
108: * <p> This method is intended for use when loading an
109: * image from a variety of sources, such as from
110: * persistent storage or from the network.</p>
111: *
112: * @param imageData the array of image data in a supported image format
113: * @param imageOffset the offset of the start of the data in the array
114: * @param imageLength the length of the data in the array
115: *
116: * @return the created image data
117: * @throws IllegalArgumentException if <code>imageData</code> is incorrectly
118: * formatted or otherwise cannot be decoded
119: */
120: ImageData createImmutableImageData(byte[] imageData,
121: int imageOffset, int imageLength);
122:
123: /**
124: * Creates an immutable image data using pixel data from the specified
125: * region of a source image data, transformed as specified.
126: *
127: * <p>The source image may be mutable or immutable. For immutable source
128: * images, transparency information, if any, is copied to the new
129: * image unchanged.</p>
130: *
131: * <p>On some devices, pre-transformed images may render more quickly
132: * than images that are transformed on the fly using
133: * <code>drawRegion</code>.
134: * However, creating such images does consume additional heap space,
135: * so this technique should be applied only to images whose rendering
136: * speed is critical.</p>
137: *
138: * <p>The transform function used must be one of the following, as defined
139: * in the {@link javax.microedition.lcdui.game.Sprite Sprite} class:<br>
140: *
141: * <code>Sprite.TRANS_NONE</code> - causes the specified image
142: * region to be copied unchanged<br>
143: * <code>Sprite.TRANS_ROT90</code> - causes the specified image
144: * region to be rotated clockwise by 90 degrees.<br>
145: * <code>Sprite.TRANS_ROT180</code> - causes the specified image
146: * region to be rotated clockwise by 180 degrees.<br>
147: * <code>Sprite.TRANS_ROT270</code> - causes the specified image
148: * region to be rotated clockwise by 270 degrees.<br>
149: * <code>Sprite.TRANS_MIRROR</code> - causes the specified image
150: * region to be reflected about its vertical center.<br>
151: * <code>Sprite.TRANS_MIRROR_ROT90</code> - causes the specified image
152: * region to be reflected about its vertical center and then rotated
153: * clockwise by 90 degrees.<br>
154: * <code>Sprite.TRANS_MIRROR_ROT180</code> - causes the specified image
155: * region to be reflected about its vertical center and then rotated
156: * clockwise by 180 degrees.<br>
157: * <code>Sprite.TRANS_MIRROR_ROT270</code> - causes the specified image
158: * region to be reflected about its vertical center and then rotated
159: * clockwise by 270 degrees.<br></p>
160: *
161: * <p>
162: * The size of the returned image will be the size of the specified region
163: * with the transform applied. For example, if the region is
164: * <code>100 x 50</code> pixels and the transform is
165: * <code>TRANS_ROT90</code>, the
166: * returned image will be <code>50 x 100</code> pixels.</p>
167: *
168: * <p><strong>Note:</strong> If all of the following conditions
169: * are met, this method may
170: * simply return the source <code>Image</code> without creating a
171: * new one:</p>
172: * <ul>
173: * <li>the source image is immutable;</li>
174: * <li>the region represents the entire source image; and</li>
175: * <li>the transform is <code>TRANS_NONE</code>.</li>
176: * </ul>
177: *
178: * @param imageData the source image data to be copied from
179: * @param x the horizontal location of the region to be copied
180: * @param y the vertical location of the region to be copied
181: * @param width the width of the region to be copied
182: * @param height the height of the region to be copied
183: * @param transform the transform to be applied to the region
184: * @return the new immutable image data
185: *
186: */
187: ImageData createImmutableImageData(ImageData imageData, int x,
188: int y, int width, int height, int transform);
189:
190: /**
191: * Creates an immutable image data from decoded image data obtained from an
192: * <code>InputStream</code>. This method blocks until all image data has
193: * been read and decoded. After this method completes (whether by
194: * returning or by throwing an exception) the stream is left open and its
195: * current position is undefined.
196: *
197: * @param stream the name of the resource containing the image data
198: * in one of the supported image formats
199: *
200: * @return the created image data
201: * @throws java.io.IOException if an I/O error occurs, if the image data
202: * cannot be loaded, or if the image data cannot be decoded
203: *
204: */
205: ImageData createImmutableImageData(InputStream stream)
206: throws IOException;
207:
208: /**
209: * Creates an immutable image data from a sequence of ARGB values,
210: * specified
211: * as <code>0xAARRGGBB</code>.
212: * The ARGB data within the <code>rgb</code> array is arranged
213: * horizontally from left to right within each row,
214: * row by row from top to bottom.
215: * If <code>processAlpha</code> is <code>true</code>,
216: * the high-order byte specifies opacity; that is,
217: * <code>0x00RRGGBB</code> specifies
218: * a fully transparent pixel and <code>0xFFRRGGBB</code> specifies
219: * a fully opaque
220: * pixel. Intermediate alpha values specify semitransparency. If the
221: * implementation does not support alpha blending for image rendering
222: * operations, it must replace any semitransparent pixels with fully
223: * transparent pixels. (See <a href="#alpha">Alpha Processing</a>
224: * for further discussion.) If <code>processAlpha</code> is
225: * <code>false</code>, the alpha values
226: * are ignored and all pixels must be treated as fully opaque.
227: *
228: * <p>Consider <code>P(a,b)</code> to be the value of the pixel
229: * located at column <code>a</code> and row <code>b</code> of the
230: * Image, where rows and columns are numbered downward from the
231: * top starting at zero, and columns are numbered rightward from
232: * the left starting at zero. This operation can then be defined
233: * as:</p>
234: *
235: * <TABLE BORDER="2">
236: * <TR>
237: * <TD ROWSPAN="1" COLSPAN="1">
238: * <pre><code>
239: * P(a, b) = rgb[a + b * width]; </code></pre>
240: * </TD>
241: * </TR>
242: * </TABLE>
243: * <p>for</p>
244: *
245: * <TABLE BORDER="2">
246: * <TR>
247: * <TD ROWSPAN="1" COLSPAN="1">
248: * <pre><code>
249: * 0 <= a < width
250: * 0 <= b < height </code></pre>
251: * </TD>
252: * </TR>
253: * </TABLE>
254: * <p> </p>
255: *
256: * @param rgb an array of ARGB values that composes the image
257: * @param width the width of the image
258: * @param height the height of the image
259: * @param processAlpha <code>true</code> if <code>rgb</code>
260: * has an alpha channel,
261: * <code>false</code> if all pixels are fully opaque
262: * @return the created immutable image data
263: */
264: ImageData createImmutableImageData(int rgb[], int width,
265: int height, boolean processAlpha);
266:
267: /**
268: * Create a immutable image from romized image data.
269: *
270: * @param imageDataArrayPtr native pointer to image data as Java int
271: * @param imageDataArrayLength length of image data array
272: * @throws IllegalArgumentException if the id is invalid
273: * @return the created image data
274: */
275: ImageData createImmutableImageData(int imageDataArrayPtr,
276: int imageDataArrayLength);
277: }
|