|
JSR-184 Public Review Draft - Apr. 30, 2003. | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.microedition.m3d.Object3D | +--javax.microedition.m3d.Node | +--javax.microedition.m3d.Camera
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.
Clipping is done according to the OpenGL 1.3 specification, section 2.11, with the exception that user-defined clip planes are not supported.
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 |
public static final int GENERIC
Specifies a generic 4x4 projection matrix.
public static final int PERSPECTIVE
Specifies a perspective projection matrix.
public static final int PARALLEL
Specifies a parallel projection matrix.
Constructor Detail |
public Camera()
Constructs a new Camera node with default values. The default values are as follows:
PARALLEL
Method Detail |
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.
height
- total height of the view volumeaspectRatio
- aspect ratio of the viewport, that is, width
divided by heightnear
- 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
java.lang.IllegalArgumentException
- if height <= 0
java.lang.IllegalArgumentException
- if aspectRatio <= 0
java.lang.IllegalArgumentException
- if near = far
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.
fovy
- field of view in the vertical direction, in degreesaspectRatio
- aspect ratio of the viewport (width divided by height)near
- 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
java.lang.IllegalArgumentException
- if near = far
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.
transform
- a Transform object to copy as the new projection matrix
java.lang.IllegalArgumentException
- if transform
is not invertiblepublic 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.
transform
- a Transform object to populate with the matrix, or
null to only return the type of projection
GENERIC
, PERSPECTIVE
,
or PARALLEL
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.length < 4
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.
mask
- a bitmask specifying which Nodes to test for intersectionx
- X coordinate of the point on the viewport plane through which to cast the rayy
- Y coordinate of the point on the viewport plane through which to cast the rayri
- 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
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 IndexBufferGroup.pick
|
JSR-184 Public Review Draft - Apr. 30, 2003. | ||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |