|
MID Profile | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.microedition.lcdui.Image
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.
Images are either mutable or immutable 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 as blank images
containing only white pixels. The application may render on a mutable image
by calling getGraphics()
on the Image
to obtain
a Graphics
object
expressly for this purpose.
Images
may be placed within Alert
,
Choice
, Form
, or ImageItem
objects.
The high-level user interface implementation may need to update the display
at any time, without notifying the application. In order to provide
predictable behavior, the high-level user interface
objects provide snapshot semantics for the image. That is, when a mutable
image is placed within an Alert
, Choice
,
Form
, or ImageItem
object,
the effect is as if a snapshot is taken of its current contents. This
snapshot is then used for all subsequent painting of the high-level user
interface component. If the application modifies the contents of the
image, the application must update the component containing the image (for
example, by calling ImageItem.setImage
) in order to
make the modified
contents visible.
An immutable image may be created from a mutable image through the
use of the createImage
method. It is possible
to create a mutable copy of an immutable image using a technique similar
to the following:
|
Every pixel within a mutable image is always fully opaque. Immutable
images may contain a combination of fully opaque pixels
(alpha = 2bitdepth - 1)
, fully
transparent pixels (alpha = 0
), and
semitransparent pixels
(0 < alpha <
2bitdepth - 1
),
where bitdepth is the number of bits per sample in the source data.
Implementations must support storage, processing, and rendering of fully opaque pixels and fully transparent pixels in immutable images. When creating an image from source data (whether from a PNG file or from an array of ARGB data), a fully opaque pixel in the source data must always result in a fully opaque pixel in the new image, and a fully transparent pixel in the source data must always result in a fully transparent pixel in the new image.
The required treatment of semitransparent pixel data depends upon
whether the implementation supports alpha blending at rendering time. If
the implementation supports alpha blending, a semitransparent pixel in the
source data must result in a semitransparent pixel in the new image. The
resulting alpha value may be modified to accommodate the number of levels
of semitransparency supported by the platform. (See the Display.numAlphaLevels()
method.) If an
implementation does not support alpha blending, any semitransparent pixels
in the source data must be replaced with fully transparent pixels in the
new image.
Implementations are required to support images stored in the PNG format, as specified by the PNG (Portable Network Graphics) Specification, Version 1.0. All conforming MIDP implementations are also conformant to the minimum set of requirements given by the PNG Specification. MIDP implementations also must conform to additional requirements given here with respect to handling of PNG images. Note that the requirements listed here take precedence over any conflicting recommendations given in the PNG Specification.
All of the 'critical' chunks specified by PNG must be supported. The paragraphs below describe these critical chunks.
The IHDR chunk. MIDP devices must handle the following values in the IHDR chunk:
Image
object must match
the dimensions of the PNG image. That is, the values returned by
getWidth()
and getHeight()
and the rendered width and height must
equal the width and height specified in the IHDR chunk.4
& 6
(grayscale
with alpha and RGB with alpha,
respectively) the alpha channel must be decoded. Any pixels with an alpha
value of zero must be treated as transparent. Any pixels with an alpha
value of 255
(for images with 8
bits per
sample) or 65535
(for images with
16
bits per sample) must be treated as opaque. If
rendering with alpha
blending is supported, any pixels with intermediate alpha values must be
carried through to the resulting image. If alpha blending is not
supported, any pixels with intermediate alpha values must be replaced with
fully transparent pixels.0
(deflate) is the only
supported compression method.
This method utilizes the "zlib" compression scheme, which
is also used for
jar files; thus, the decompression (inflate) code may be shared between the
jar decoding and PNG decoding implementations. As noted in the PNG
specification, the compressed data stream may comprised internally of both
compressed and uncompressed (raw) data.
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
.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.The PLTE chunk. Palette-based images must be supported.
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).
The IEND chunk. This chunk must be found in order for the image to be considered valid.
PNG defines several 'ancillary' chunks that may be present in a PNG image but are not critical for image decoding.
The tRNS chunk. All implementations must support the tRNS chunk.
This chunk is used to implement transparency without providing alpha
channel data for each pixel. For color types 0
and
2
, a particular
gray or RGB value is defined to be a transparent pixel. In this case, the
implementation must treat pixels with this value as fully transparent.
Pixel value comparison must be based on the actual pixel values using the
original sample depth; that is, this comparison must be performed before
the pixel values are resampled to reflect the display capabilities
of the device. For color type 3
(indexed color),
8
-bit alpha values are
potentially provided for each entry in the color palette. In this case,
the implementation must treat pixels with an alpha value of
0
as fully
transparent, and it must treat pixels with an alpha value of
255
as fully
opaque. If rendering with alpha blending is supported, any pixels with
intermediate alpha values must be carried through to the resulting image.
If alpha blending is not supported, any pixels with intermediate alpha
values must be replaced with fully transparent pixels.
The implementation may (but is not required to) support any of the other ancillary chunks. The implementation must silently ignore any unsupported ancillary chunks that it encounters. The currently defined optional ancillary chunks are:
cHRM gAMA hIST iCCP iTXt pHYs sBIT sPLT sRGB tEXt tIME zTXt
PNG (Portable Network Graphics) Specification, Version 1.0. 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.
Method Summary | |
static Image |
createImage(byte[] imageData,
int imageOffset,
int imageLength)
Creates an immutable image which is decoded from the data stored in the specified byte array at the specified offset and length. |
static Image |
createImage(Image source)
Creates an immutable image from a source image. |
static Image |
createImage(Image image,
int x,
int y,
int width,
int height,
int transform)
Creates an immutable image using pixel data from the specified region of a source image, transformed as specified. |
static Image |
createImage(InputStream stream)
Creates an immutable image from decoded image data obtained from an InputStream . |
static Image |
createImage(int width,
int height)
Creates a new, mutable image for off-screen drawing. |
static Image |
createImage(String name)
Creates an immutable image from decoded image data obtained from the named resource. |
static Image |
createRGBImage(int[] rgb,
int width,
int height,
boolean processAlpha)
Creates an immutable image from a sequence of ARGB values, specified as 0xAARRGGBB . |
Graphics |
getGraphics()
Creates a new Graphics object that renders to this
image. |
int |
getHeight()
Gets the height of the image in pixels. |
void |
getRGB(int[] rgbData,
int offset,
int scanlength,
int x,
int y,
int width,
int height)
Obtains ARGB pixel data from the specified region of this image and stores it in the provided array of integers. |
int |
getWidth()
Gets the width of the image in pixels. |
boolean |
isMutable()
Check if this image is mutable. |
Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Method Detail |
public static Image createImage(int width, int height)
width
- the width of the new image, in pixelsheight
- the height of the new image, in pixelsIllegalArgumentException
- if either width
or
height
is zero or lesspublic static Image createImage(Image source)
This method is useful for placing the contents of mutable images
into Choice
objects. The application can create
an off-screen image
using the
createImage(w, h)
method, draw into it using a Graphics
object
obtained with the
getGraphics()
method, and then create an immutable copy of it with this method.
The immutable copy may then be placed into Choice
objects.
source
- the source image to be copiedNullPointerException
- if source
is null
public static Image createImage(String name) throws IOException
Class.getResourceAsStream(name)
. The rules for resolving resource
names are defined in the
Application Resource Files section of the
java.lang
package documentation.name
- the name of the resource containing the image data in one of
the supported image formatsNullPointerException
- if name
is null
IOException
- if the resource does not exist,
the data cannot
be loaded, or the image data cannot be decodedpublic static Image createImage(byte[] imageData, int imageOffset, int imageLength)
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
.
This method is intended for use when loading an image from a variety of sources, such as from persistent storage or from the network.
imageData
- the array of image data in a supported image formatimageOffset
- the offset of the start of the data in the arrayimageLength
- the length of the data in the arrayArrayIndexOutOfBoundsException
- if imageOffset
and imageLength
specify an invalid rangeNullPointerException
- if imageData
is
null
IllegalArgumentException
- if imageData
is incorrectly
formatted or otherwise cannot be decodedpublic static Image createImage(Image image, int x, int y, int width, int height, int transform)
The source image may be mutable or immutable. For immutable source images, transparency information, if any, is copied to the new image unchanged.
On some devices, pre-transformed images may render more quickly
than images that are transformed on the fly using
drawRegion
.
However, creating such images does consume additional heap space,
so this technique should be applied only to images whose rendering
speed is critical.
The transform function used must be one of the following, as defined
in the Sprite
class:
Sprite.TRANS_NONE
- causes the specified image
region to be copied unchanged
Sprite.TRANS_ROT90
- causes the specified image
region to be rotated clockwise by 90 degrees.
Sprite.TRANS_ROT180
- causes the specified image
region to be rotated clockwise by 180 degrees.
Sprite.TRANS_ROT270
- causes the specified image
region to be rotated clockwise by 270 degrees.
Sprite.TRANS_MIRROR
- causes the specified image
region to be reflected about its vertical center.
Sprite.TRANS_MIRROR_ROT90
- causes the specified image
region to be reflected about its vertical center and then rotated
clockwise by 90 degrees.
Sprite.TRANS_MIRROR_ROT180
- causes the specified image
region to be reflected about its vertical center and then rotated
clockwise by 180 degrees.
Sprite.TRANS_MIRROR_ROT270
- causes the specified image
region to be reflected about its vertical center and then rotated
clockwise by 270 degrees.
The size of the returned image will be the size of the specified region
with the transform applied. For example, if the region is
100 x 50
pixels and the transform is
TRANS_ROT90
, the
returned image will be 50 x 100
pixels.
Note: If all of the following conditions
are met, this method may
simply return the source Image
without creating a
new one:
TRANS_NONE
.image
- the source image to be copied fromx
- the horizontal location of the region to be copiedy
- the vertical location of the region to be copiedwidth
- the width of the region to be copiedheight
- the height of the region to be copiedtransform
- the transform to be applied to the regionNullPointerException
- if image
is null
IllegalArgumentException
- if the region to be copied exceeds
the bounds of the source imageIllegalArgumentException
- if either width
or
height
is zero or lessIllegalArgumentException
- if the transform
is not validpublic Graphics getGraphics()
Graphics
object that renders to this
image. This image
must be
mutable; it is illegal to call this method on an immutable image.
The mutability of an image may be tested
with the isMutable()
method.
The newly created Graphics
object has the
following properties:
Image
object;Image
;Font.getDefaultFont()
;SOLID
; and
The lifetime of Graphics
objects created using
this method is
indefinite. They may be used at any time, by any thread.
Graphics
object with this image as its destinationIllegalStateException
- if the image is immutablepublic int getWidth()
public int getHeight()
public boolean isMutable()
Graphics
object
obtained from the
getGraphics()
method of this object.true
if the image is mutable,
false
otherwisepublic static Image createImage(InputStream stream) throws IOException
InputStream
. This method blocks until all image data has
been read and decoded. After this method completes (whether by
returning or by throwing an exception) the stream is left open and its
current position is undefined.stream
- the name of the resource containing the image data
in one of the supported image formatsNullPointerException
- if stream
is null
IOException
- if an I/O error occurs, if the image data
cannot be loaded, or if the image data cannot be decodedpublic static Image createRGBImage(int[] rgb, int width, int height, boolean processAlpha)
0xAARRGGBB
.
The ARGB data within the rgb
array is arranged
horizontally from left to right within each row,
row by row from top to bottom.
If processAlpha
is true
,
the high-order byte specifies opacity; that is,
0x00RRGGBB
specifies
a fully transparent pixel and 0xFFRRGGBB
specifies
a fully opaque
pixel. Intermediate alpha values specify semitransparency. If the
implementation does not support alpha blending for image rendering
operations, it must replace any semitransparent pixels with fully
transparent pixels. (See Alpha Processing
for further discussion.) If processAlpha
is
false
, the alpha values
are ignored and all pixels must be treated as fully opaque.
Consider P(a,b)
to be the value of the pixel
located at column a
and row b
of the
Image, where rows and columns are numbered downward from the
top starting at zero, and columns are numbered rightward from
the left starting at zero. This operation can then be defined
as:
|
for
|
rgb
- an array of ARGB values that composes the imagewidth
- the width of the imageheight
- the height of the imageprocessAlpha
- true
if rgb
has an alpha channel,
false
if all pixels are fully opaqueNullPointerException
- if rgb
is null
.IllegalArgumentException
- if either width
or
height
is zero or lessArrayIndexOutOfBoundsException
- if the length of
rgb
is
less than width * height
.public void getRGB(int[] rgbData, int offset, int scanlength, int x, int y, int width, int height)
0xAARRGGBB
format, where the high-order
byte contains the
alpha channel and the remaining bytes contain color components for
red, green and blue, respectively. The alpha channel specifies the
opacity of the pixel, where a value of 0x00
represents a pixel that
is fully transparent and a value of 0xFF
represents a fully opaque
pixel.
The returned values are not guaranteed to be identical to values
from the original source, such as from
createRGBImage
or from a PNG
image. Color values may be resampled to reflect the display
capabilities of the device (for example, red, green or blue pixels may
all be represented by the same gray value on a grayscale device). On
devices that do not support alpha blending, the alpha value will be
0xFF
for opaque pixels and 0x00
for
all other pixels (see Alpha Processing for further discussion.) On devices
that support alpha blending, alpha channel values may be resampled to
reflect the number of levels of semitransparency supported.
The scanlength
specifies the relative offset within the
array between the corresponding pixels of consecutive rows. In order
to prevent rows of stored pixels from overlapping, the absolute value
of scanlength
must be greater than or equal to
width
. Negative values of scanlength
are
allowed. In all cases, this must result in every reference being
within the bounds of the rgbData
array.
Consider P(a,b)
to be the value of the pixel
located at column a
and row b
of the
Image, where rows and columns are numbered downward from the
top starting at zero, and columns are numbered rightward from
the left starting at zero. This operation can then be defined
as:
|
for
|
The source rectangle is required to not exceed the bounds of the image. This means:
|
If any of these conditions is not met an
IllegalArgumentException
is thrown. Otherwise, in
cases where width <= 0
or height <= 0
,
no exception is thrown, and no pixel data is copied to
rgbData
.
rgbData
- an array of integers in which the ARGB pixel data is
storedoffset
- the index into the array where the first ARGB value
is storedscanlength
- the relative offset in the array between
corresponding pixels in consecutive rows of the regionx
- the x-coordinate of the upper left corner of the regiony
- the y-coordinate of the upper left corner of the regionwidth
- the width of the regionheight
- the height of the regionArrayIndexOutOfBoundsException
- if the requested operation would
attempt to access an element in the rgbData
array
whose index is either
negative or beyond its length (the contents of the array are unchanged)IllegalArgumentException
- if the area being retrieved
exceeds the bounds of the source imageIllegalArgumentException
- if the absolute value of
scanlength
is less than width
NullPointerException
- if rgbData
is null
|
MID Profile | |||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |