javax.microedition.lcdui
Class ScalableImage

java.lang.Object
  javax.microedition.lcdui.Image
      javax.microedition.lcdui.ScalableImage

public class ScalableImage
extends Image

A ScalableImage object encapsulates vector graphics content. The enclosed vector content can be used directly in high-level LCDUI components, and can also be used (in a rasterized, bitmap form) as an Image of variable dimensions in low-level graphics APIs.

Vector graphics content has a viewport to define the area within its own coordinate system that should be rendered. Typically, the viewport region is defined by the content author (e.g. using the viewBox attribute in SVG) and is sized to contain all of its drawing operations. If a viewport is not explicitly defined in the content, the implementation may examine the drawing operations to determine a suitable viewport; if such an examination is unfeasible or not supported by the implementation, a default viewport of (0, 0, 100, 100) may be used instead. The viewport dimensions may be obtained using the getViewportWidth() and getViewportHeight() methods.

As a subclass of Image, a ScalableImage also has a pixel-based width and height, as reported by the getWidth() and getHeight() methods. For a ScalableImage, these values indicate its rasterized size when used as a pixel-based Image in low-level graphics API's, and they are initially set to match the content's viewport dimensions. The pixel dimensions of the image may be subsequently modified using the setWidth() and setHeight() methods, thus changing the size of the rasterized Image that it represents; however, it is important to note that such changes do not alter the viewport of the content itself. The initial frame of the content is rasterized if the content includes animations.

When used with high-level UI components, the implementation SHOULD use the vector-based content directly and render it at a size that is appropriate for the given component. The size may be determined based on the content's viewport size and the preferred image dimensions for the Display. Support for animation is OPTIONAL and interactive functionality MAY be disabled. The pixel-based dimensions of a ScalableImage may be ignored when it is used in this manner.

Creating ScalableImages

A ScalableImage instance can be created by calling one of the following factory methods in the Image class with valid vector graphics content (e.g. SVG Tiny 1.1):

• createImage(byte[] data, int imageOffset, int imageLength)
• createImage(InputStream in)
• createImage(String resource)

All ScalableImage objects are immutable and cannot be drawn on with a Graphics object; calls to isMutable() will return false and an attempt to obtain a Graphics object will result in an IllegalStateException being thrown. The LCDUI does not provide any capabilities to modify the content of the ScalableImage. Any modifications to the vector-based content are done through an auxiliary vector graphics API like M2G, if the ScalableImage has been created using the bind(Object) method.

Creating Pixel-Based Images From ScalableImages

As stated above, a ScalableImage itself can be used directly as a regular pixel-based Image for low-level graphics APIs. However, it is also possible create a pixel-based Image instance from a ScalableImage by using it as the source for the following factory methods in Image:

• createImage(Image source)
• createImage(Image source, int x, int y, int width, int height, int transform)
• createImage(Image source, int x, int y, int width, int height, int transform, int img_width, int img_height)

Use of ScalableImage with Sprite and TiledLayer

A ScalableImage may be used with the Sprite and TiledLayer class in the Game API. However, since these APIs assume fixed image dimensions, the implementation must behave as if a fixed-size, bitmapped snapshot of the ScalableImage is taken when the relevant method is invoked. That is, the following code:

 new Sprite(myScalableImage);
 

must behave as:

 new Sprite(Image.createImage(myScalableImage));
 

Thus, subsequent changes to the dimensions or content of the ScalableImage do not effect the size or appearance of the Sprite or TiledLayer.

Since:

MIDP 3.0

Method Summary

static ScalableImage	bind(java.lang.Object extScalableImage) Binds a ScalableImage instance to a more advanced scalable image object from an external graphics API.
int	getViewportHeight() Gets the height of the content's viewport.
int	getViewportWidth() Gets the width of the content's viewport.
void	setHeight(int height, boolean matchAspectRatio) Sets the pixel-based height of the ScalableImage, as returned by getHeight.
void	setWidth(int width, boolean matchAspectRatio) Sets the pixel-based width of the ScalableImage, as returned by getWidth.
void	unbind() Unbinds this ScalableImage instance from an external scalable image object.

Methods inherited from class javax.microedition.lcdui.Image

createImage, createImage, createImage, createImage, createImage, createImage, createImage, createImage, createRGBImage, getARGB16, getGraphics, getHeight, getRGB, getRGB16, getWidth, hasAlpha, isAnimated, isMutable, isScalable

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getViewportWidth

public int getViewportWidth()

Gets the width of the content's viewport.

Returns:

the viewport width

getViewportHeight

public int getViewportHeight()

Gets the height of the content's viewport.

Returns:

the viewport height

bind

public static ScalableImage bind(java.lang.Object extScalableImage)

Binds a ScalableImage instance to a more advanced scalable image object from an external graphics API. This method creates and returns a new scalable image instance that can be used for drawing within LCDUI. If this method is called again for the same target, it MUST return the same ScalableImage instance that was returned from the initial call to this method.

For example, M2G has the javax.microedition.m2g.ScalableImage class. This method allows to get a javax.microedition.lcdui.ScalableImage representation out of javax.microedition.m2g.ScalableImage.

As long as the binding is in effect (i.e. the unbind method has not been called), modifications to extScalableImage MUST be visible directly in the ScalableImage object returned from the method.

Parameters:

extScalableImage - the external scalable image object to bind to

Returns:

ScalableImage instance bound to external API scalable image object

Throws:

java.lang.NullPointerException - if target is null

java.lang.IllegalArgumentException - if target is invalid

unbind

public void unbind()

Unbinds this ScalableImage instance from an external scalable image object. From the point unbind() is called, modifications to the previously bound external scalable image will no longer be reflected in this ScalableImage instance. The data and attributes of the ScalableImage reflect the state of the external scalable image at the point unbind() was called. If the instance is not bound to an external object, this method does nothing.

See Also:

bind(java.lang.Object)

setWidth

public void setWidth(int width,
                     boolean matchAspectRatio)

Sets the pixel-based width of the ScalableImage, as returned by getWidth. This dimension only applies when the image is used as a pixel-based Image in low-level graphics APIs such as drawImage.

If matchAspectRatio is true, the pixel-based height is automatically changed to match the aspect ratio of the content's viewport given the new width. Mathematically:

     height = (getViewportHeight() * width) / getViewportWidth()
 

Parameters:

width - The new pixel-based width of the image, in pixels

matchAspectRatio - true if the height should be changed to match the content's aspect ratio

Throws:

java.lang.IllegalArgumentException - if width is not a positive value

setHeight

public void setHeight(int height,
                      boolean matchAspectRatio)

Sets the pixel-based height of the ScalableImage, as returned by getHeight. This dimension only applies when the image is used as a pixel-based Image in low-level graphics APIs such as drawImage.

If matchAspectRatio is true, the pixel-based width is automatically changed to match the aspect ratio of the content's viewport given the new height. Mathematically:

     width = (viewport_width * height) / viewport_height
 

Parameters:

height - The new pixel-based height of the image, in pixels

matchAspectRatio - true if the width should be changed to match the content's aspect ratio

Throws:

java.lang.IllegalArgumentException - if height is not a positive value