Previous
Classes
Index
Next
| DirectX Media for Animation Java Reference |
Previous |
Classes |
Index |
Next |
public class CameraBvr extends Behavior {
// Methods
public CameraBvr depth(NumberBvr d);
public CameraBvr depthResolution(NumberBvr n);
public CameraBvr transform(Transform3Bvr xf);
public static CameraBvr newUninitBvr();
public static CameraBvr parallelCamera(NumberBvr n);
public static CameraBvr perspectiveCamera(NumberBvr projdst, NumberBvr nearclip);
}
Creates an object that represents a camera behavior. A camera is used with the render method to project geometry onto an infinite two-dimensional image. Related operations include rendering it into a microphone to extract the sound, or into a pair of microphones to extract stereo sounds.
There are two basic types of cameras: one for parallel projection and one for perspective projection. Both cameras are oriented so that they gaze in the negative z direction, with positive y considered "up." Also, both cameras have a near clipping plane. This plane (a product of Z-buffered rendering) specifies the closest distance at which an object is visible. Objects closer than the near clipping plane cannot be seen.
Cameras are manipulated via standard three-dimensional transform operations. These transforms modify the camera characteristics and also position and orient the cameras. For more information about these operations, see the transform methods described below.
For more information about behaviors, see the Behavior class.
public CameraBvr depth(NumberBvr d);Creates a new camera behavior that is the result of applying the specified depth to the original behavior. By default, cameras have infinite depth, which means that all objects in front of the camera are visible. The new behavior is a CameraBvr whose maximum viewing depth is the NumberBvr depth. If depth < 0, the CameraBvr will be unable to see anything. If you prefer to think in terms of hither and yon, this method sets yon = hither + depth. It is important to note that depth is the limit on the far plane. As with the near plane, the geometry is bounded as tightly as possible for maximum Z-resolution.
Limiting the depth of the camera is useful for preserving depth resolution when using Z-buffered rendering. It is also useful for a camera inside a building, where no viewing region is larger than some value.
Return Value:
Returns the CameraBvr object.
Parameter Description d The NumberBvr object that sets the maximum viewing depth of the CameraBvr.
public CameraBvr depthResolution(NumberBvr res);Creates a new camera behavior that is the result of applying the specified res to the original behavior. The res parameter is the minimum depth (in camera coordinates) that is guaranteed to be distinct. The new CameraBvr meets this requirement and also sets the depth to be as deep as possible. Because of the nature of Z-resolution, the depth is dependent on the projection point and will change depending on the amount of perspective. For example, if the projection point is at (0, 0, 2), an image clip is at (0, 0, 1) and the depth resolution is 1cm, then the CameraBvr has a depth of slightly over 25.1m. It is important to note that depth represents the limit on the far plane. As with the near plane, the geometry is bounded as tightly as possible for maximum Z-resolution.
Return Value:
Returns the CameraBvr object.
Parameter Description res The NumberBvr object that sets the minimum depth (in camera coordinates) that is guaranteed to be distinct.
public CameraBvr transform(Transform3Bvr xf);Cameras are modified, positioned, and oriented via standard transforms. Scale transforms modify the camera while translations and rotations position and orient the camera. The basic steps for using a camera are defining it, modifying it if necessary, and then placing it in the scene.
It is important to note that all camera scales should be applied before camera rotations, and that only scales, rotations, and translations are supported on cameras. Transformations that do not meet these criteria will yield a camera with undefined behavior.
There are two types of scale transformations called Z-scales and X/Y-scales. Z-scales must be positive, non-zero values. Z-scales affect the position of the near clipping plane (if the clipping plane is set to a non-zero value.) For example, if the near clipping plane is located at 10 (that is, if Z=10), then a scale of [1 1 3] will yield a near clipping plane located at Z=30. More importantly, Z-scales move the projection point for a perspective camera. This means an increasing Z-scale yields a perspective camera that is zooming in, and a decreasing Z-scale yields a perspective camera that is zooming out.
Use X/Y-scales to affect the size of the projected image. One way to think of this is that an X/Y-scale sets the size of the camera relative to the world it's viewing. For example, if you are viewing a microscopic scene, use a small X/Y-scale. On the other hand, if you are viewing a solar system, use a large X/Y scale. Scaling a camera by some value in X/Y is exactly equivalent to inversely scaling the resulting image by the same amount. For example, scaling the camera by [10 10 1] is the same as scaling the resulting image by [1/10 1/10]. Finally, disparate scales in X and Y can be used to change the aspect ratio of the rendered image.
Once the camera is defined (via construction and scaling), it can be placed in the scene via rotations and translations just as a light source, microphone, or any other geometric object is placed.
Return Value:
Returns the CameraBvr object.
Parameter Description xf The Transform3Bvr object. Remarks:
This attribute composes values.
public static CameraBvr newUninitBvr();Allows you to refer to a camera behavior before that behavior has been defined. With this method you can create a camera behavior and use it in the definition of other behaviors, but not actually define its contents until some later point. (This is accomplished with the init method, which is available on all behaviors.) The system generates a run-time error if you initialize a non-uninitialized behavior, initialize an uninitialized behavior that has already been initialized, or run an initialized behavior that has not yet been initialized.
Return Value:
Returns the CameraBvr object.
public static CameraBvr parallelCamera(NumberBvr n);Creates a parallel camera for parallel (or orthographic) projection. The parallel camera is transformed the same way as the perspective camera, except that Z-scales have no effect (note, however, that zero or negative Z-scales yield undefined results).
Prior to transformation, the parallel camera gazes in the negative z-direction, with positive y considered as "up."
Return Value:
Returns the CameraBvr object.
Parameter Description n The NumberBvr object that is the Z-location of the near clipping plane.
public static CameraBvr perspectiveCamera(NumberBvr projdst, NumberBvr nearclip);Creates a perspective camera for perspective rendering. On creation, the projection plane (the plane at which objects appear as their actual size) is located at Z=0, the projection point is located at [0 0 projdist], and the near clipping plane is located at [0 0 nearclip].
The projdst parameter specifies the distance between the projection plane and the projection point, and must be greater than zero. The smaller this distance, the more of a wide-angle effect is achieved. The larger this distance, the more of a telephoto effect is achieved.
The nearclip parameter specifies the Z-location of the near clipping plane and must be less than projdst. In other words, the near clipping plane must lie on the same side of the projection point as the projection plane. Although it is tempting to place the near clipping plane as close as possible to the projection point, Z-buffer precision is lost dramatically as the near clipping plane gets closer to the projection point. (The main result of such precision loss is that far objects are rendered in front of near objects.)
Return Value:
Returns the CameraBvr object.
Parameter Description projdst The NumberBvr object that is the Z-location of the projection point. It must be greater than zero. nearclip The NumberBvr object that is the Z-location of the near clipping plane. It must be less than projdst. Remarks:
The following diagram shows a model of the perspective camera. Note that the nearclip need not be in front of the projection plane.
© 1997 Microsoft Corporation. All rights reserved. Legal Notices.