
M3G 1.1  Jun 22, 2005  
PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 
java.lang.Object javax.microedition.m3g.Object3D javax.microedition.m3g.Transformable javax.microedition.m3g.Node javax.microedition.m3g.Camera
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
where (x y z w) are the clipspace 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.
Clipping is done according to the OpenGL 1.3 specification, section 2.11, with the exception that userdefined 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 clipspace 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.
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 
public static final int GENERIC
Specifies a generic 4x4 projection matrix.
public static final int PARALLEL
Specifies a parallel projection matrix.
public static final int PERSPECTIVE
Specifies a perspective projection matrix.
Constructor Detail 
public Camera()
Constructs a new Camera node with default values. The default values are as follows:
GENERIC
Method Detail 
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
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.
fovy
 height of the view volume in camera coordinatesaspectRatio
 aspect ratio of the viewport, that is, width
divided by heightnear
 distance to the front clipping plane in camera spacefar
 distance to the back clipping plane in camera space
java.lang.IllegalArgumentException
 if height <= 0
java.lang.IllegalArgumentException
 if aspectRatio <= 0
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
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.
fovy
 field of view in the vertical direction, in degreesaspectRatio
 aspect ratio of the viewport, that is, width
divided by heightnear
 distance to the front clipping planefar
 distance to the back clipping plane
java.lang.IllegalArgumentException
 if any argument is <= 0
java.lang.IllegalArgumentException
 if fovy >= 180
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 speedup 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 reprojection cases; stereoscopic rendering; and some shadow algorithms.
transform
 a Transform object to copy as the new projection matrix
java.lang.NullPointerException
 if transform
is nullpublic 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.
transform
 a Transform object to populate with the matrix, or
null to only return the type of projection
GENERIC
,
PERSPECTIVE
, or PARALLEL
java.lang.ArithmeticException
 if the transformation matrix cannot be
computed due to illegal perspective or parallel projection
parameters (that is, if near == far
)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.
params
 float array to fill in with the four projection
parameters, or null to only return the type of projection
GENERIC
,
PERSPECTIVE
, or PARALLEL
java.lang.IllegalArgumentException
 if (params != null) &&
(params.length < 4)

M3G 1.1  Jun 22, 2005  
PREV CLASS NEXT CLASS  FRAMES NO FRAMES  
SUMMARY: NESTED  FIELD  CONSTR  METHOD  DETAIL: FIELD  CONSTR  METHOD 