com.motorola.iden.micro3d
Class Renderer

java.lang.Object
  |
  +--com.motorola.iden.micro3d.Renderer

public class Renderer

extends java.lang.Object

Provides 3D rendering capability.

The Renderer class is used for rendering a frame from the Micro3D engine. All objects to be rendered must first be registered with the Renderer. The objects are registered for rendering with the draw() method. The specified Object3D will then be added to an internal queue. The frame can be rendered to either a Graphics object or a texture. When rendering to a Graphics object the method paint(Graphics g) is used. For rendering to a texture the method paint(Texture t, int color) is used. Once an object has been rendered, it is removed from the queue.

When an Object3D is registered for rendering, the Layout3D, texture, and sphere texture (if available) is also stored in the internal queue. As a result, the layout, texture, and sphere texture must be assigned to an Object3D before it is registered for rendering, or the Object3D might not be rendered correctly. Since all of the above parameters are stored when the object is registered for rendering, it is possible to render multiple instances of the same figure with different layouts, textures, or sphere textures. The example below illustrates rendering the same figure twice with different layout and texture.

// setup the first instance of the figure figure.setTexture(texture1); figure.setLayout(layout1); // register the first instance for rendering renderer.draw(figure, 10, 10); // setup the second instance of the figure figure.setTexture(texture2); figure.setLayout(layout2); // register the second instance for rendering renderer.draw(figure, 20, 20); // render the frame renderer.paint(g);

The maximum number of objects that can be registered at one time is 65535. After that any request to register additional object will be ignored. The Object3D will be rendered on the buffer at the position specified.

Z-Ordering

Z-ordering is handled automatically by the 3D engine. In order to make use of the engine's Z-Ordering capabilities, all objects that are registred with the draw() method between calls to Renderer's paint methods will be Z-ordered regardless of the order in which the objects were added.

MOTOROLA and the Stylized M Logo are registered trademarks of Motorola, Inc. Reg. U.S. Pat. & Tm. Off.
© COPYRIGHT 2003-2004 MOTOROLA, Inc. All Rights Reserved.

Constructor Summary

Renderer()
Creates a new Renderer.

Method Summary

void	draw(Object3D object3d, int x, int y) Registers an Object3D to be drawn by this Renderer the next time paint() method is called.
void	paint(javax.microedition.lcdui.Graphics g) Paints the primitives and figures registered with this Renderer to the specified Graphics object.
Texture	paint(Texture texture, int color) Paints the primitives and figures registered with this Renderer to the specified Texture object.

Methods inherited from class java.lang.Object

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

Constructor Detail

Renderer

public Renderer()

Creates a new Renderer.

Method Detail

draw

public void draw(Object3D object3d,
                 int x,
                 int y)
          throws java.lang.NullPointerException

Registers an Object3D to be drawn by this Renderer the next time paint() method is called. The Object3D will be rendered on the buffer at the position specified by the x and y parameters. If the origin of the graphics context has been translated with g.translate() method, the object will be rendered according to the translation.

The x and y values should be within the range -2048 to 2047. Values smaller than -2048 will be set to -2048, and values greater than 2047 will be set to 2047.

The maximum number of objects that can be registered at one time is 65535. After that any request to register additional object will be ignored. However, in most cases, the maximum number of objects that can be registered will be limited by the amount of available memory.

Parameters:

object3d - the Object3D to render with this Renderer.

Throws:

java.lang.NullPointerException - if Object3D is null.

See Also:

Object3D

paint

public void paint(javax.microedition.lcdui.Graphics g)

Paints the primitives and figures registered with this Renderer to the specified Graphics object.

When this method is called, all the Object3D objects that have been registered with this Renderer will be rendered to the specified graphics buffer. Once the objects are rendered, they are removed from the internal queue. If this method is invoked when there are no objects registered with the Renderer, the specfied Graphics objects is not modified.

Parameters:

g - the Graphics object to paint to.

Throws:

java.lang.NullPointerException - if g is null.

paint

public Texture paint(Texture texture,
                     int color)
              throws java.lang.IllegalArgumentException

Paints the primitives and figures registered with this Renderer to the specified Texture object. This method works just like the paint(Graphics g), except the result is rendered to a Texture object. This texture can then be applied to a figure or a primitive and rendered on the screen. The color parameter defines a color that will be applied to the entire surface of the texture before anything is renderer to the texture.

There are two ways to render to a texture. One is to specify an existing texture object as the parameter. In this case, the existing texture will be destroyed and overwriten with the result of this method. If the specified Texture is an existing regular or sphere texture that has never been rendered to, a new Texture object will be allocated and a reference to that new object will be returned upon successful completion of this method. The size of the new texture is fixed at 256x256 pixels. If the specified Texture is an existing texture that has been previously used as a target texture for rendering, then the texture will be modified and the same reference will be returned upon successful completion of this method. Rendering to a sphere texture is not supported by the Micro3D engine. If the specified texture is a sphere texture, the sphere texture will be destroyed and in its place a regular texture will be created.
The second way to render to a texture is to specify null as the target texture. In this case, a new Texture object will be allocated, and it will be returned by this method upon completion of the rendering. The size of the new texture is fixed at 256x256 pixels. When rendering to a texture it is recommended to re-use the same texture object as much as possible, since frequent allocations of a new texture will have a negative impact on the speed of the application.

Parameters:

texture - the Texture object to be painted to, or null for a new Texture.

color - the background color for the Texture.

Returns:

the Texture object painted to.

Throws:

java.lang.IllegalArgumentException - if the specified texture is a MultiTexture.

See Also:

Texture, paint(Graphics g)