Figure 1. The Sprite Processing Command Model
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
|
+--javax.microedition.lcdui.Displayable
|
+--javax.microedition.lcdui.Canvas
|
+--com.vodafone.v10.graphics.sprite.SpriteCanvas
SpriteCanvas class provides the Canvas for manipulating Sprite data.
SpriteCanvas inherits the MIDP Canvas class. In addition to the functions of the Canvas class, it provides functions for sprite drawing. A Java application creates and uses instances of SpriteCanvas or its subclasses.
The SpriteCanvas drawing functions are used in the same way as the ordinary Canvas subclass, by calling the Display object setCurrent() method and designating the SpriteCanvas object as current Displayable, then calling the SpriteCanvas method.
Functions other than SpriteCanvas drawing, such as those for key event control, should be implemented along the same lines as the Canvas class methods. For example, waiting for a key event can be implemented by overriding the Canvas class keyPressed() or other such method.
Sprite data is graphical data made up of 256-color pixels and consisting of square blocks that are 8 pixels by 8 pixels in size. The SpriteCanvas class provides the functions for drawing sprite data on a virtual screen or in a frame buffer, and for performing image processing such as horizontal flip, vertical flip, rotate, and color data designation from a color palette.
A handset has one virtual screen, whose size is dependent on the handset design. The virtual screen contents can be copied to a frame buffer. The frame buffer is a kind of screen buffer belonging to the SpriteCanvas object; the Java application must create this buffer using a SpriteCanvas method.
A typical way of using this functionality is to have the Java application draw the background image on the virtual screen, copy that to the frame buffer, and after drawing sprite data on top of that background, copying the entire frame buffer contents to the real screen. The image copied to the real screen is what the user sees in the handset display. The Java application performs all this processing using SpriteCanvas methods. Note that drawing on the virtual screen can be done using the MIDP Graphics class functions in addition to sprite data drawing.
The drawing of sprite data is here described in terms of "sprite processing commands." The concept of sprite processing commands is illustrated in Figure 1.
Figure 1. The Sprite Processing Command Model
The Java application readies 8-pixel-square sprite data and registers it in the SpriteCanvas object. The SpriteCanvas object stores the sprite data array. When a draw is executed that involves image processing, the sprite data stored by the SpriteCanvas object is not affected.
When a sprite processing command is executed, the sprite data and the nature of the image processing are designated. In the example in Figure 1, sprite processing commands cmd1, cmd2, cmd3, and cmd4 are performed on sprite data A, each designating a different angle of rotation. Commands cmd5, cmd6, and cmd9 apply to sprite data C, with each designating a different color conversion.
A Java application uses a SpriteCanvas method to create a sprite processing command, and requests sprite drawing by designating the command as well as the draw destination position when it calls a SpriteCanvas drawing method. A method must be called each time a sprite drawing action is performed. There are separate drawing methods for virtual screen and frame buffer drawing.
The data structure used with the SpriteCanvas class is explained here.
The sprite data structure is shown in Figure 2.
Figure 2. Sprite Data Structure
One unit of sprite data consists of a 64-pixel block (8 pixels by 8 pixels), with each pixel represented by one byte. Data must be arrayed in the direction shown in the left part of Figure 2.
When a Java application creates the SpriteCanvas object, it designates in the constructor the number of sprite data elements (max. 256) that can be registered. The SpriteCanvas object builds a sprite data array internally with this number of elements. The Java application must register each element in this array using the setPattern() method. As shown in Figure 2 on the right, these elements are designated by an index value from 0 to 255. The index values are used in the sprite processing commands described later.
Figure 3. Sprite Data Color Palette
The byte representing each pixel of sprite data is a color palette index indicating an array (color palette) made up of 24-bit colors (palette values), as shown in Figure 3. The color palette is made up of 4-byte integer values. Each palette value represents a color in the 24-bit RGB color space, and is calculated based on RGB 1-byte values as R*0x10000 + G*0x100 + B. Once the pixel value is known, the color of that pixel as a 24-bit color can be determined from the color palette array elements (called "palette entries" hereafter).
When a Java application creates the SpriteCanvas object, it designates the number of palette colors (max. 256) that can be registered. The SpriteCanvas object builds a color palette array internally with this number of elements. The palette value upon creation is 0. The Java application must register each element in this array using the setPalette() method.
Sprite processing commands are created by means of the createCharacterCommand() method. The items shown in Table 1 are designated as parameters with this method.
| Item | Description |
| offset | Palette offset (0 to 7): This value multiplied by 32 is added to each pixel value of sprite data, and the lower byte of the result becomes the color palette index value that determines the color of the pixel. By changing the offset value, the same sprite data can be drawn in different colors. Note that when drawing is being performed in the frame buffer and transparent is "true," pixels having a pixel value of 0 are regarded as transparent and the offset value is not reflected in the drawing result. |
| transparent | Transparent color use (false: transparent color not used; true: transparent color used): When drawing takes place in the frame buffer and transparent is "true," those pixels whose color value is 0 are treated as transparent and are drawn with the same color as the background color already drawn. In all other cases, i.e., when drawing on the virtual screen or when drawing in the frame buffer while transparent is "false," all pixels take the color of the color palette value as determined by palette offset processing based on the designated offset value. |
| rotation | Rotation (0: no rotation; 1: 90 degrees; 2: 180 degrees; 3: 270 degrees): Sprite data is rotated clockwise by the designated number of degrees. |
| isUpsideDown | Vertical flip (false: no flip; true: flip): When this value is "true," the sprite data is inverted vertically. |
| isRightsideLeft | Horizontal flip (false: no flip; true: flip): When this value is "true," the sprite data is inverted horizontally. |
| patternNo | Sprite number: The sprite data to which a command applies, designated by sprite data array index. |
Image processing designated in the sprite processing commands is performed in the order Rotate, Flip vertically, Flip horizontally.
A Java application creates sprite processing commands by calling the SpriteCanvas createCharacterCommand() method, designating the items in Table 2-1. It then uses these commands to issue drawing requests to the drawSpriteChar() method for drawing in the frame buffer, or to the drawBackground() method for drawing on the virtual screen.
Figure 4. Image Buffers (Virtual Screen and Frame Buffer) and the Real Screen
Two kinds of screen buffers are used with SpriteCanvas, a "virtual screen" and "frame buffer." The final image seen by the user on the handset display is that copied from the frame buffer to the real screen. The relationship among these screens is illustrated in Figure 4.
getVirtualWidth() and getVirtualHeight().
createFrameBuffer() method to create one frame buffer. The width and height of the frame buffer are designated at this time, and must be no larger than the real screen size.
The frame buffer uses handset memory resources. When drawing by the SpriteCanvas object is not required, the frame buffer memory area can be freed using the disposeFrameBuffer() method, although any drawing data in the frame buffer at the time will be lost. Note also that if a method is called that assumes the existence of a frame buffer and none is currently created, an exception will be thrown.
copyArea() method, designating the area to be copied and the destination coordinates.
The frame buffer contents are copied to the real screen by calling the drawFrameBuffer() method, designating the copy destination coordinates on the real screen. The size of the area to be copied is the same as the frame buffer size. copyFullScreen() method and designating the destination coordinates (dx, dy). In the example shown in Figure 5, both dx and dy are designated as positive values.
Figure 5. Virtual Screen Scrolling
copyArea(), drawFrameBuffer() or copyFullScreen(), that part is simply discarded without throwing an exception.
An outline of the procedures when a Java application uses the SpriteCanvas class is shown in Figure 6. The names at the right of the figure are method names.
Figure 6. Using the SpriteCanvas Class
The Java application creates an instance of SpriteCanvas or of its subclass. It sets in the SpriteCanvas constructor the maximum number of sprite data elements and the maximum number of color palette entries that can be registered. The SpriteCanvas object keeps a sprite data array and color palette array based on the designated numbers.
The Java application registers the individual sprite data elements in the SpriteCanvas object using the setPattern() method, and registers the palette colors using the setPalette() method. Once the sprite data and color palette have been set, sprite data can be drawn.
The Java application calls the Display object setCurrent() method and sets the created SpriteCanvas object as current Displayable.
The Java application creates a frame buffer by calling the SpriteCanvas createFrameBuffer() method, designating the width and height of the frame buffer as parameters. Make sure these dimensions are no larger than the real screen dimensions.
For drawing sprite data, the Java application builds sprite processing commands by calling the createCharacterCommand() method. It then uses the drawSpriteChar() method to draw in the frame buffer and the drawBackground() method to draw on the virtual screen, designating sprite processing commands and screen positions (in the frame buffer or virtual screen) in either case.
Contents of the virtual screen are scrolled using the copyFullScreen() method, and are copied to the frame buffer using the copyArea() method.
The images drawn in the frame buffer are then copied to the real screen by means of the drawFrameBuffer() method, making them visible to the user.
When no sprite drawing is taking place, the disposeFrameBuffer() method may be called to free the frame buffer. Then when drawing is resumed, the frame buffer must be created anew using createFrameBuffer().
Use of SpriteCanvas is ended by setting a different Displayable subclass object to current Displayable.
Notes:
setPattern() and setPalette() are made right after SpriteCanvas is created; but this is not the only time these settings can be made. They may be set at any time so long as it is before the start of drawing on the virtual screen or frame buffer; and the settings may be changed at any time.
drawBackground() method and the Graphics drawing-related methods. Drawing using the Graphics class is basically the same as that using the ordinary Canvas class functions. In this case the Canvas class paint() method is overridden and Graphics drawing methods are called. A difference from ordinary drawing using the Canvas class is that in order to display the drawn images on the handset, after copying the virtual screen contents to the frame buffer using the SpriteCanvas copyArea(), they must then be transferred to the real screen using drawFrameBuffer().
drawBackground() method is to draw the background image, the transparency designation in a sprite processing command is ignored. Accordingly, pixels with value 0 are drawn using the palette color stored at index 0.
| Fields inherited from class javax.microedition.lcdui.Canvas |
DOWN, FIRE, GAME_A, GAME_B, GAME_C, GAME_D, KEY_NUM0, KEY_NUM1, KEY_NUM2, KEY_NUM3, KEY_NUM4, KEY_NUM5, KEY_NUM6, KEY_NUM7, KEY_NUM8, KEY_NUM9, KEY_POUND, KEY_STAR, LEFT, RIGHT, UP |
| Constructor Summary | |
SpriteCanvas(int numPalettes,
int numPatterns)
SpriteCanvas constructor |
|
| Method Summary | |
void |
copyArea(int sx,
int sy,
int fw,
int fh,
int tx,
int ty)
Transfers a rectangular area of the virtual screen to the frame buffer. |
void |
copyFullScreen(int tx,
int ty)
Copies the entire virtual screen to a designated position on the virtual screen. |
static short |
createCharacterCommand(int offset,
boolean transparent,
int rotation,
boolean isUpsideDown,
boolean isRightsideLeft,
int patternNo)
Creates sprite processing commands. |
void |
createFrameBuffer(int fw,
int fh)
Creates a frame buffer. |
void |
disposeFrameBuffer()
Terminates use of the sprite function. |
void |
drawBackground(short command,
short x,
short y)
Draws a sprite in the virtual screen. |
void |
drawFrameBuffer(int tx,
int ty)
Transfers the frame buffer contents to the real screen. |
void |
drawSpriteChar(short command,
short x,
short y)
Draws a sprite in the frame buffer. |
static int |
getVirtualHeight()
Gets the virtual screen height. |
static int |
getVirtualWidth()
Gets the virtual screen width. |
void |
setPalette(int index,
int palette)
Sets a palette entry. |
void |
setPattern(int index,
byte[] data)
Sets sprite data. |
| Methods inherited from class javax.microedition.lcdui.Canvas |
getGameAction, getHeight, getKeyCode, getKeyName, getWidth, hasPointerEvents, hasPointerMotionEvents, hasRepeatEvents, hideNotify, isDoubleBuffered, keyPressed, keyReleased, keyRepeated, paint, pointerDragged, pointerPressed, pointerReleased, repaint, repaint, serviceRepaints, showNotify |
| Methods inherited from class javax.microedition.lcdui.Displayable |
addCommand, isShown, removeCommand, setCommandListener |
| Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
public SpriteCanvas(int numPalettes,
int numPatterns)
numPalettes - Palette entry countnumPatterns - Sprite data countIllegalArgumentException - if numPalettes or numPatterns is outside the
range of 1 to 256.| Method Detail |
public void createFrameBuffer(int fw,
int fh)
fw - Frame buffer widthfh - Frame buffer heightIllegalStateException - if the frame buffer already exists.IllegalArgumentException - if the frame buffer size is larger than the
real screen.RuntimeException - if the native sprite function failed to create a
frame buffer.public void disposeFrameBuffer()
public static int getVirtualWidth()
public static int getVirtualHeight()
public void setPalette(int index,
int palette)
index - Palette indexpalette - Palette entryArrayIndexOutOfBoundsException - if the palette index exceeds the value
designated in the constructor.RuntimeException - if the setting operation failed in the native sprite
function.
public void setPattern(int index,
byte[] data)
index - Sprite data indexdata - Sprite dataArrayIndexOutOfBoundsException - if the sprite data index exceeds the
value designated in the constructor.IllegalArgumentException - if the array size is not 64.RuntimeException - if the setting operation failed in the native sprite
function.
public static short createCharacterCommand(int offset,
boolean transparent,
int rotation,
boolean isUpsideDown,
boolean isRightsideLeft,
int patternNo)
offset - Palette index offset (0 to 7)transparent - Transparent color use (false: transparent color not used;
true: transparent color used)rotation - Clockwise rotation (0: no rotation; 1: 90 degrees; 2: 180
degrees; 3: 270 degrees)isUpsideDown - Vertical flip (false: no flip; true: flip)isRightsideLeft - Horizontal flip (false: no flip; true: flip)patternNo - Sprite data indexIllegalArgumentException - if an illegal value is designated.
public void drawSpriteChar(short command,
short x,
short y)
command - Sprite processing commandx - The x coordinate for sprite drawingy - The y coordinate for sprite drawingIllegalArgumentException - if the sprite data index set in the command
parameter exceeds the value designated in the constructor.IllegalStateException - if the frame buffer was not yet created.RuntimeException - if the drawing operation failed in the native sprite
function.
public void drawBackground(short command,
short x,
short y)
Designate in the command parameter the sprite processing commands created using createCharacterCommand(). Note that transparency settings in the commands are ignored in the case of virtual screen drawing.
Drawing does not take place if the SpriteCanvas object has not been set to current Displayable using the Display object setCurrent() method.
command - Sprite processing commandx - The x coordinate for sprite drawing (8-pixel units)y - The y coordinate for sprite drawing (8-pixel units)IllegalArgumentException - if the sprite data index exceeds the value
designated in the constructor.RuntimeException - if the drawing operation failed in the native sprite
function.
public void copyArea(int sx,
int sy,
int fw,
int fh,
int tx,
int ty)
The frame buffer contents are overwritten.
Transfer does not take place if the SpriteCanvas object has not been set to current Displayable using the Display object setCurrent() method.
sx - Upper left corner of rectangle (x coordinate on virtual screen)sy - Upper left corner of rectangle (y coordinate on virtual screen)fw - Width of the rectangular areafh - Height of the rectangular areatx - Destination x coordinate (in frame buffer)ty - Destination y coordinate (in frame buffer)IllegalStateException - if the frame buffer was not yet created.IllegalArgumentException - if sx or sy is a negative value.IllegalArgumentException - if fw or fh is larger than the frame buffer size.RuntimeException - if the operation failed in the native sprite function.
public void copyFullScreen(int tx,
int ty)
Copying does not take place if the SpriteCanvas object has not been set to current Displayable using the Display object setCurrent() method.
tx - Destination x coordinatety - Destination y coordinateRuntimeException - if the operation failed in the native sprite function.
public void drawFrameBuffer(int tx,
int ty)
tx - Destination x coordinate (on the real screen)ty - Destination y coordinate (on the real screen)IllegalStateException - if the frame buffer was not yet created.RuntimeException - if the transfer operation failed in the native
sprite function.
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||