javax.microedition.m3d
Class Camera

java.lang.Object
  |
  +--javax.microedition.m3d.Object3D
        |
        +--javax.microedition.m3d.Node
              |
              +--javax.microedition.m3d.Camera

public class Camera

extends Node

Camera defines parameters for projecting the 3D world to the display. The camera is always facing towards the negative Z axis, (0 0 -1), in its local coordinate system. The camera can be positioned and oriented in the same way as any other Node; that is, using the node transformation and alignment methods.

The projection matrix transforms 3D homogeneous coordinates from camera space to clip space. Triangles are clipped to the view volume, which is defined by

-w <= x <= w
-w <= y <= w
-w <= z <= w


where (x, y, z, w) are the clip-space coordinates of a vertex.

Subsequent to clipping, x, y, and z are divided by w to obtain normalized device coordinates. These are between [-1, 1], and the center of the viewport lies at the origin. Finally, the viewport mapping is applied to transform the normalized x, y and z into window coordinates. The viewport mapping is specified in Graphics3D.

Implementation guidelines

Clipping is done according to the OpenGL 1.3 specification, section 2.11, with the exception that user-defined clip planes are not supported.

See Also:

Binary format

Field Summary

static int	GENERIC Specifies a generic 4x4 projection matrix.
static int	PARALLEL Specifies a parallel projection matrix.
static int	PERSPECTIVE Specifies a perspective projection matrix.

Fields inherited from class javax.microedition.m3d.Node

NONE, ORIGIN, X_AXIS, Y_AXIS, Z_AXIS

Fields inherited from class javax.microedition.m3d.Object3D

userObject

Constructor Summary

Camera()
Constructs a new Camera node with default values.

Method Summary

int	getProjection(float[] params) Gets the current projection parameters and type.
int	getProjection(Transform transform) Gets the current projection matrix and type.
boolean	pick(int mask, float x, float y, RayIntersection ri) Picks the first enabled Mesh or Sprite in the World that is intercepted by the given pick ray and is in the specified scope.
void	setGeneric(Transform transform) Sets the given generic transformation as the current projection matrix.
void	setParallel(float height, float aspectRatio, float near, float far) Constructs a parallel projection matrix and sets that as the current projection matrix.
void	setPerspective(float fovy, float aspectRatio, float near, float far) Constructs a perspective projection matrix and sets that as the current projection matrix.

Methods inherited from class javax.microedition.m3d.Node

getAlphaFactor, getOrientation, getParent, getScale, getScopeID, getTransform, getTransformTo, getTranslation, isEnabled, setAlignment, setAlphaFactor, setEnable, setOrientation, setScale, setScopeID, setTransform, setTranslation

Methods inherited from class javax.microedition.m3d.Object3D

addAnimationTrack, animate, clone, find, getAnimationTrack, getAnimationTrackCount, getReferences, getUserID, removeAnimationTrack, setUserID

Methods inherited from class java.lang.Object

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

Field Detail

GENERIC

public static final int GENERIC

Specifies a generic 4x4 projection matrix.

See Also:

Constant Field Values

PERSPECTIVE

public static final int PERSPECTIVE

Specifies a perspective projection matrix.

See Also:

Constant Field Values

PARALLEL

public static final int PARALLEL

Specifies a parallel projection matrix.

See Also:

Constant Field Values

Constructor Detail

Camera

public Camera()

Constructs a new Camera node with default values. The default values are as follows:

projection mode : PARALLEL
view volume : opposite corners at (-1 -1 -1) and (1 1 1)

Method Detail

setParallel

public void setParallel(float height,
                        float aspectRatio,
                        float near,
                        float far)

Constructs a parallel projection matrix and sets that as the current projection matrix. Note that the near and far clipping planes may be in arbitrary order, although usually near < far, but they must not be equal.

Denoting the width, height and depth of the view volume by w, h and d, respectively, the parallel projection matrix P is constructed as follows.

     |   2/w         0            0               0       |
     |    0         2/h           0               0       |
 P = |    0          0          -2/d       -(near+far)/d  |
     |    0          0            0               1       |

where

 h = height
 w = aspectRatio * h
 d = far - near

The rendered image will "stretch" to fill the entire viewport defined in Graphics3D. It is therefore recommended that the aspect ratio given here be equal to the aspect ratio of the viewport. Otherwise, the image will appear elongated in either the horizontal or the vertical direction. No attempt is made to correct this effect automatically, for example by adjusting the height of the view volume, because the implementation does not know how the application developer would prefer that correction to be done.

Parameters:

height - total height of the view volume

aspectRatio - aspect ratio of the viewport, that is, width divided by height

near - distance to the front clipping plane; may be negative or greater than far

far - distance to the back clipping plane; may be negative or less than near

Throws:

java.lang.IllegalArgumentException - if height <= 0

java.lang.IllegalArgumentException - if aspectRatio <= 0

java.lang.IllegalArgumentException - if near = far

setPerspective

public void setPerspective(float fovy,
                           float aspectRatio,
                           float near,
                           float far)

Constructs a perspective projection matrix and sets that as the current projection matrix. Note that the near and far clipping planes may be in arbitrary order, although usually near < far, but they must not be equal.

Denoting the width, height and depth of the view frustum by w, h and d, respectively, the perspective projection matrix P is constructed as follows.

     |   1/w         0            0               0       |
     |    0         1/h           0               0       |
 P = |    0          0      -(near+far)/d   -2*near*far/d |
     |    0          0           -1               0       |

where

 h = tan(fovy/2)
 w = aspectRatio * h
 d = far - near

The rendered image will "stretch" to fill the entire viewport defined in Graphics3D. It is therefore recommended that the aspect ratio given here be equal to the aspect ratio of the viewport. Otherwise, the image will appear elongated in either the horizontal or the vertical direction. No attempt is made to correct this effect automatically, for example by adjusting the field of view, because the implementation does not know how the application developer would prefer that correction to be done.

Parameters:

fovy - field of view in the vertical direction, in degrees

aspectRatio - aspect ratio of the viewport (width divided by height)

near - distance to the front clipping plane

far - distance to the back clipping plane

Throws:

java.lang.IllegalArgumentException - if any argument is <= 0

java.lang.IllegalArgumentException - if fovy >= 180

java.lang.IllegalArgumentException - if near = far

setGeneric

public void setGeneric(Transform transform)

Sets the given generic transformation as the current projection matrix. The contents of the given transformation are copied in, so any further changes to it will not affect the current projection matrix. Various rendering tricks are possible by using a generic projection matrix. For example, the far clipping plane can be set to infinity, allowing the application to view an arbitrarily large scene.

Parameters:

transform - a Transform object to copy as the new projection matrix

Throws:

java.lang.IllegalArgumentException - if transform is not invertible

getProjection

public int getProjection(Transform transform)

Gets the current projection matrix and type. This method is available regardless of the type of projection, since parallel and perspective transformations can always be returned in the 4x4 matrix form.

Parameters:

transform - a Transform object to populate with the matrix, or null to only return the type of projection

Returns:

the type of projection: GENERIC, PERSPECTIVE, or PARALLEL

getProjection

public int getProjection(float[] params)

Gets the current projection parameters and type. The given float array is populated with the projection parameters in the same order as they are supplied to the respective set methods, setPerspective and setParallel. If the projection type is GENERIC, the float array is left untouched. This is the case even if the generic projection matrix actually is a perspective or parallel projection.

Parameters:

params - float array to fill in with the four projection parameters, or null to only return the type of projection

Returns:

the type of projection: GENERIC, PERSPECTIVE, or PARALLEL

Throws:

java.lang.IllegalArgumentException - if params.length < 4

pick

public boolean pick(int mask,
                    float x,
                    float y,
                    RayIntersection ri)

Picks the first enabled Mesh or Sprite in the World that is intercepted by the given pick ray and is in the specified scope. Nodes that are disabled or out scope are ignored. Information about the picked object, if any, is filled in to the given RayIntersection object. If no intersection occurs, the RayIntersection object is left unmodified.

The pick ray is cast towards infinity from a point p' on the near clipping plane, through a point p'' on the far clipping plane. p' and p'' are computed from the given point p = (x, y), by back-projecting it to the near and far clipping planes. The given (x, y) coordinates are relative to the viewport, such that (0, 0) is the upper left corner and (1, 1) is the lower right corner. However, the coordinates are not restricted to that range and may take on any values.

A node whose scope membership ID does not match with the given scope mask is not picked, even if it would intersect the pick ray. A scope ID is defined to match with a mask if and only if scopeID & mask != 0, where & denotes bitwise AND.

Note that the distance to the picked object, returned in RayIntersection, is the distance from p' to the object, not the distance from this Camera to the object.

Parameters:

mask - a bitmask specifying which Nodes to test for intersection

x - X coordinate of the point on the viewport plane through which to cast the ray

y - Y coordinate of the point on the viewport plane through which to cast the ray

ri - a RayIntersection object to fill in with information about the intersected Mesh or Sprite, or null to just find out whether the ray intersected something or not

Returns:

true if the ray intersected a visible Node; false otherwise

Throws:

java.lang.IllegalStateException - if this Camera is not part of a World

java.lang.IllegalStateException - if any Mesh that is tested for intersection violates the constraints defined in Mesh, MorphingMesh, SkinnedMesh, VertexBuffer, or IndexBuffer

See Also:

Group.pick