com.motorola.iden.micro3d
Class PointSprite

java.lang.Object
  |
  +--com.motorola.iden.micro3d.Object3D
        |
        +--com.motorola.iden.micro3d.Primitive
              |
              +--com.motorola.iden.micro3d.PointSprite

public class PointSprite

extends Primitive

PointSprite primitive. The PointSprite primitive is a texture mapped quadrilateral polygon that is always facing the view direction. The PointSprite supports blending types and color key transparency. Environment mapping is not supported by PointSprite. If a sphere texture is assigned, it will be ignored and it will not affect rendering. PointSprite also will not be affected by the lighting parameters.

A PointSprite is defined by a single Vector3D object which contains the coordinates for the upper left-hand corner of the PointSprite along with the width and height of the point sprite. Therefore the valid vertex ID for the PointSprite is Primitive.VERTEX_A. It is not possible to assign a vertex normal or a face normal to a point sprite.

The texture for the PointSprite is defined by specifying the X and Y coordinates for the upper left-hand corned of the target texture, along with the desired width and height. In addition, it is possible to specify a rotation angle for the point sprite.

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.

Field Summary

static int	LOCAL_SIZE Specifies that a sprite's dimensions are in terms of the model coordinate system.
static int	PARALLEL_PROJECTION Disables perspective projection when rendering a sprite.
static int	PERSPECTIVE_PROJECTION Enables perspective projection when rendering a sprite.
static int	PIXEL_SIZE Specifies that a sprite's dimensions are in terms of the screen coordinate system.

Fields inherited from class com.motorola.iden.micro3d.Primitive

BLENDING_ADD, BLENDING_HALF, BLENDING_NONE, BLENDING_SUB, FACE_NORMAL, NORMAL, VERTEX_A, VERTEX_B, VERTEX_C, VERTEX_D

Constructor Summary

PointSprite(Vector3D vertexA, int width, int height, int rotation, int textureX, int textureY, int textureWidth, int textureHeight, int displayType, Layout3D layout, Texture texture)
Creates a PointSprite primitive at the position specified by the vertexA parameter.

Method Summary

int	getColor() Returns 0 since PointSprite does not support colors when rendering.
int	getDisplayType() Returns the display directive value for this PointSprite.
int	getHeight() Returns the height of the PointSprite.
int	getRotation() Returns the rotation of the PointSprite.
int	getTextureCoordinateX(int vertexID) Returns the X component of the texture coordinate for the specified vertex.
int	getTextureCoordinateY(int vertexID) Returns the Y component of the texture coordinate for the specified vertex.
Vector3D	getVector(int vectorID) Returns the Vector3D for the specified vertex.
int	getWidth() Returns the width of the PointSprite.
void	setColor(int color) This method is not supported by PointSprite and so does not perform any functionality.
void	setDisplayType(int displayType) Specifies whether the PointSprite's size is relative to the screen or model coordinate system and enables perspective projection on the PointSprite.
void	setHeight(int height) Sets the height of the PointSprite.
void	setRotation(int rotation) Sets the rotation angle of the PointSprite.
void	setTextureCoordinates(int vertexID, int x, int y) Sets the texture coordinates for the specified vertex.
void	setVector(int vectorID, Vector3D vector) Sets the specified vertex to the Vector3D provided.
void	setWidth(int width) Sets the width of the PointSprite.

Methods inherited from class com.motorola.iden.micro3d.Primitive

enableColorKeyTransparency, getBlendingType, hasColorKeyTransparency, setBlendingType

Methods inherited from class com.motorola.iden.micro3d.Object3D

getLayout, getSphereTexture, getTexture, setLayout, setSphereTexture, setTexture

Methods inherited from class java.lang.Object

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

Field Detail

LOCAL_SIZE

public static final int LOCAL_SIZE

Specifies that a sprite's dimensions are in terms of the model coordinate system.

PIXEL_SIZE

public static final int PIXEL_SIZE

Specifies that a sprite's dimensions are in terms of the screen coordinate system.

PERSPECTIVE_PROJECTION

public static final int PERSPECTIVE_PROJECTION

Enables perspective projection when rendering a sprite.

PARALLEL_PROJECTION

public static final int PARALLEL_PROJECTION

Disables perspective projection when rendering a sprite.

Constructor Detail

PointSprite

public PointSprite(Vector3D vertexA,
                   int width,
                   int height,
                   int rotation,
                   int textureX,
                   int textureY,
                   int textureWidth,
                   int textureHeight,
                   int displayType,
                   Layout3D layout,
                   Texture texture)
            throws java.lang.NullPointerException,
                   java.lang.IllegalArgumentException

Creates a PointSprite primitive at the position specified by the vertexA parameter. The PointSprite will be rendered using the specified texture and Layout3D. Portions of the Texture to use for the point sprite can be specified using the textureX, textureY, textureWidth, and textureHeight parameters. The size and rotation of the sprite can be specified using width, height, and rotation parameters where 360 degrees is equivalent to 4096.

The displayType parameter will determine the actual size of the point sprite and how it will be rendered on the screen. The displayType parameter is created by combining one of the display type size constants with one of the display type perspective constants. For example to create a PointSprite with pixel size and perspective the displayType parameter will be (PointSprite.PIXEL_SIZE | PointSprite.PERSPECTIVE_PROJECTION). The results are summarized in the table below.

Projecton Method in Layout3D	Display type (size)	Display type (perspective)	Explanation
Perspective Projection	LOCAL_SIZE	PERSPECTIVE_PROJECTION	The size of the point sprite in the view coordinate system.
	LOCAL_SIZE	PARALLEL_PROJECTION	Undefined - will not render correctly
	PIXEL_SIZE	PERSPECTIVE_PROJECTION	The size of the point sprite in the screen coordinate system after it is projected onto the near clipping plane.
	PIXEL_SIZE	PARALLEL_PROJECTION	The size of point sprite in the screen coordinate system.
Parallel Projection	LOCAL_SIZE	PERSPECTIVE_PROJECTION	The size of the point sprite in the view coordinate system
	LOCAL_SIZE	PARALLEL_PROJECTION
	PIXEL_SIZE	PERSPECTIVE_PROJECTION	The size of the point sprite in the screen coordinate system
	PIXEL_SIZE	PARALLEL_PROJECTION

The specified vertex cannot be null. If the specified Texture or Layout3D is null the PointSprite will not be rendered. The specified width and height parameters must be greater than zero. If the texture coordinates define a region that is outside the texture boundaries, the point sprite will not be rendered correctly.

Parameters:

vertexA - the vertex for the PointSprite.

width - the width of the PointSprite.

height - the height of the PointSprite.

rotation - the angle of rotation of the PointSprite.

textureX - the x coordinate in the texture that will map to the PointSprite.

textureY - the y coordinate in the texture that will map to the PointSprite.

textureWidth - the width of an area of the texture that will map to the PointSprite.

textureHeight - the height of an area of the texture that will map to the PointSprite.

displayType - specifies whether the PointSprite's size is relative to the screen or model coordinate system and enables perspective projection on the PointSprite.

layout - the Layout3D to use to render this PointSprite.

texture - the Texture to use when rendering this PointSprite.

Throws:

java.lang.NullPointerException - if the specified vertex is null.

java.lang.IllegalArgumentException - if the width or height are negative.

See Also:

LOCAL_SIZE, PIXEL_SIZE, PERSPECTIVE_PROJECTION, PARALLEL_PROJECTION

Method Detail

getVector

public Vector3D getVector(int vectorID)
                   throws java.lang.IllegalArgumentException

Returns the Vector3D for the specified vertex. PointSprite primitive only supports the constant Primitive.VERTEX_A.

Overrides:

getVector in class Primitive

Parameters:

vectorID - the ID of the vector to return.

Returns:

the Vector3D for the specified vertex.

Throws:

java.lang.IllegalArgumentException - if an invalid vectorID is specified.

See Also:

Primitive.VERTEX_A

setVector

public void setVector(int vectorID,
                      Vector3D vector)
               throws java.lang.NullPointerException,
                      java.lang.IllegalArgumentException

Sets the specified vertex to the Vector3D provided. PointSprite primitive only supports the constant Primitive.VERTEX_A. It is not possible to assign a vertex normal or a face normal to a point sprite.

Overrides:

setVector in class Primitive

Parameters:

vectorID - the ID of the vector being set.

vector - the Vector3D to set.

Throws:

java.lang.IllegalArgumentException - if an invalid vectorID is specified.

java.lang.NullPointerException - if the vector is null.

See Also:

Primitive.VERTEX_A

getColor

public int getColor()

Returns 0 since PointSprite does not support colors when rendering.

Overrides:

getColor in class Primitive

Returns:

since color is not used, always returns 0.

setColor

public void setColor(int color)

This method is not supported by PointSprite and so does not perform any functionality. The color value passed in is not stored.

Overrides:

setColor in class Primitive

Parameters:

color - the color value.

getDisplayType

public int getDisplayType()

Returns the display directive value for this PointSprite.

Returns:

displayType the display directive for this PointSprite

See Also:

LOCAL_SIZE, PIXEL_SIZE, PERSPECTIVE_PROJECTION, PARALLEL_PROJECTION

setDisplayType

public void setDisplayType(int displayType)
                    throws java.lang.IllegalArgumentException

Specifies whether the PointSprite's size is relative to the screen or model coordinate system and enables perspective projection on the PointSprite. The display type is specified by combining a size directive with a perspective directive. For example to create a PointSprite with pixel size and perspective the displayType parameter will be (PointSprite.PIXEL_SIZE | PointSprite.PERSPECTIVE_PROJECTION). See the PointSprite constructor for a summary of the possible values for the displayType parameter.

Parameters:

displayType - the display directive for this PointSprite.

See Also:

LOCAL_SIZE, PIXEL_SIZE, PERSPECTIVE_PROJECTION, PARALLEL_PROJECTION

getWidth

public int getWidth()

Returns the width of the PointSprite.

Returns:

the width of the PointSprite.

setWidth

public void setWidth(int width)
              throws java.lang.IllegalArgumentException

Sets the width of the PointSprite.

Parameters:

width - the width of the PointSprite.

Throws:

java.lang.IllegalArgumentException - if the width is less than zero.

getHeight

public int getHeight()

Returns the height of the PointSprite.

Returns:

the height of the PointSprite.

setHeight

public void setHeight(int height)
               throws java.lang.IllegalArgumentException

Sets the height of the PointSprite.

Parameters:

height - the height of the PointSprite.

Throws:

java.lang.IllegalArgumentException - if the height is less than zero.

getRotation

public int getRotation()

Returns the rotation of the PointSprite.

Returns:

the rotation of the PointSprite.

setRotation

public void setRotation(int rotation)

Sets the rotation angle of the PointSprite. For greater precision 360 degrees is equivalent to 4096.

Parameters:

rotation - the rotation angle of the PointSprite.

getTextureCoordinateX

public int getTextureCoordinateX(int vertexID)
                          throws java.lang.IllegalArgumentException

Returns the X component of the texture coordinate for the specified vertex.

Parameters:

vertexID - vertex.

Returns:

the X component of the texture coordinate for the specified vertex.

Throws:

java.lang.IllegalArgumentException - if the specified vertexID is invalid.

getTextureCoordinateY

public int getTextureCoordinateY(int vertexID)
                          throws java.lang.IllegalArgumentException

Returns the Y component of the texture coordinate for the specified vertex.

Parameters:

vertexID - vertex.

Returns:

the Y component of the texture coordinate for the specified vertex.

Throws:

java.lang.IllegalArgumentException - if the specified vertexID is invalid.

setTextureCoordinates

public void setTextureCoordinates(int vertexID,
                                  int x,
                                  int y)
                           throws java.lang.IllegalArgumentException

Sets the texture coordinates for the specified vertex. No error checking is done on the texture coordinates. If the texture coordinates define a region that is outside the texture boundaries, the point sprite will not be rendered correctly.

Parameters:

vertexID - vertex.

x - X coordinate.

y - Y coordinate.

Throws:

java.lang.IllegalArgumentException - if the specified vertexID is invalid.

See Also:

Primitive.VERTEX_A