javax.microedition.m3g
Class Camera

java.lang.Object
  javax.microedition.m3g.Object3D
      javax.microedition.m3g.Transformable
          javax.microedition.m3g.Node
              javax.microedition.m3g.Camera

public class Camera

extends Node

A scene graph node that defines the position of the viewer in the scene and the projection from 3D to 2D.

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 transformations of the camera node and its ancestors.

The projection matrix transforms homogeneous (4D) coordinates from camera space to clip space. Triangles are then 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 each vertex. A polygon is discarded by the clipper if all of its vertices have a negative W value. If a polygon crosses the W = 0 boundary, the portion of the polygon that lies on the negative side is discarded.

Subsequent to clipping, X, Y, and Z are divided by W to obtain normalized device coordinates (NDC). These are between [-1, 1], and the center of the viewport lies at the origin. Finally, the viewport mapping and the depth range are applied to transform the normalized X, Y and Z into window coordinates. The viewport and depth range mappings are 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. Clipping of colors and texture coordinates is done according to section 2.13.8.

To clarify the handling of polygons with negative clip-space W, we deviate slightly from the OpenGL specification by not only allowing implementations to discard any and all portions of polygons that lie in the region W < 0, but actually requiring them to do so.

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.m3g.Node

NONE, ORIGIN, X_AXIS, Y_AXIS, Z_AXIS

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.
void	setGeneric(Transform transform) Sets the given 4x4 transformation as the current projection matrix.
void	setParallel(float fovy, 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.m3g.Node

align, getAlignmentReference, getAlignmentTarget, getAlphaFactor, getParent, getScope, getTransformTo, isPickingEnabled, isRenderingEnabled, setAlignment, setAlphaFactor, setPickingEnable, setRenderingEnable, setScope

Methods inherited from class javax.microedition.m3g.Transformable

getCompositeTransform, getOrientation, getScale, getTransform, getTranslation, postRotate, preRotate, scale, setOrientation, setScale, setTransform, setTranslation, translate

Methods inherited from class javax.microedition.m3g.Object3D

addAnimationTrack, animate, duplicate, find, getAnimationTrack, getAnimationTrackCount, getReferences, getUserID, getUserObject, removeAnimationTrack, setUserID, setUserObject

Field Detail

GENERIC

public static final int GENERIC

Specifies a generic 4x4 projection matrix.

See Also:

Constant Field Values

PARALLEL

public static final int PARALLEL

Specifies a parallel projection matrix.

See Also:

Constant Field Values

PERSPECTIVE

public static final int PERSPECTIVE

Specifies a perspective 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 : GENERIC
• projection matrix : identity

Method Detail

setParallel

public void setParallel(float fovy,
                        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.

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
 0        0        -2/d   -(near+far)/d
 0        0          0           1
 

where

h = height (= fovy)
w = aspectRatio * h
d = far - near

The rendered image will "stretch" to fill the viewport entirely (not just the visible portion of it). It is therefore recommended that the aspect ratio given here be equal to the aspect ratio of the viewport as defined in setViewport. 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. Instead, the adjustment is left for the application developer to handle as he or she prefers.

In the special case when the near and far distance are equal, the view volume has, in fact, no volume and nothing is rendered. Implementations must detect this rather than trying to construct the projection matrix, as that would result in a divide by zero error.

Parameters:

fovy - height of the view volume in camera coordinates

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

near - distance to the front clipping plane in camera space

far - distance to the back clipping plane in camera space

Throws:

java.lang.IllegalArgumentException - if height <= 0

java.lang.IllegalArgumentException - if aspectRatio <= 0

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. If near and far are equal, nothing is rendered.

The perspective projection matrix P is constructed as follows.

 1/w         0            0               0
  0         1/h           0               0
  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 viewport entirely (not just the visible portion of it). It is therefore recommended that the aspect ratio given here be equal to the aspect ratio of the viewport as defined in setViewport. 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. Instead, the adjustment is left for the application developer to handle as he or she prefers.

In the special case when the near and far distance are equal, the view volume has, in fact, no volume and nothing is rendered. Implementations must detect this rather than trying to construct the projection matrix, as that would result in a divide by zero error.

Parameters:

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

aspectRatio - aspect ratio of the viewport, that is, 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

setGeneric

public void setGeneric(Transform transform)

Sets the given 4x4 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 projection matrix.

Generic 4x4 projection matrices are needed for various rendering tricks and speed-up techniques that otherwise could not be implemented at all, or not without incurring significant processing overhead. These include, for example, viewing an arbitrarily large scene by setting the far clipping plane to infinity; rendering a large image in pieces using oblique projection; portals; TV screens and other re-projection cases; stereoscopic rendering; and some shadow algorithms.

Parameters:

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

Throws:

java.lang.NullPointerException - if transform is null

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 projections 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

Throws:

java.lang.ArithmeticException - if the transformation matrix cannot be computed due to illegal perspective or parallel projection parameters (that is, if near == far)

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 != null) && (params.length < 4)