Class Camera


  • public final class Camera
    extends Object
    This Camera data structure represents a camera located at the origin, looking down the negative z-axis, with a near clipping plane.

    This Camera has a configurable "view volume" that determines what part of space the camera "sees" when we use the camera to take a picture (that is, when we render a Scene).

    This Camera can "take a picture" two ways, using a perspective projection or a parallel (orthographic) projection. Each way of taking a picture has a different shape for its view volume. The data in this data structure determines the shape of each of the two view volumes.

    For the perspective projection, the view volume (in view coordinates!) is the infinitely long frustum that is formed by cutting at the near clipping plane, z = -near, the infinitely long pyramid with its apex at the origin and its cross section in the image plane, z = -1, with edges x = -1, x = +1, y = -1, and y = +1. The perspective view volume's shape is set by the projPerspective() method.

    For the orthographic projection, the view volume (in view coordinates!) is the semi-infinite rectangular cylinder parallel to the z-axis, with base in the near clipping plane, z = -near, and with edges x = left, x = right, y = bottom, y = top (a semi-infinite parallelepiped). The orthographic view volume's shape is set by the projOrtho() method.

    When the graphics rendering Pipeline uses this Camera to render a Scene, the renderer only "sees" the geometry from the scene that is contained in this camera's view volume. (Notice that this means the orthographic camera can see geometry that is behind the camera. In fact, the perspective camera can also sees geometry that is behind the camera.) The renderer's NearClip and Clip pipeline stages are responsible for making sure that the scene's geometry that is outside of this camera's view volume is not visible.

    The plane z = -1 (in view coordinates) is the camera's "image plane". The rectangle in the image plane with corners (left, bottom, -1) and (right, top, -1) is the camera's "view rectangle". The view rectangle is like the film in a real camera, it is where the camera's image appears when you take a picture. The contents of the camera's view rectangle (after it gets "normalized" to camera coordinates by the renderer's View2Camera stage) is what gets rasterized, by the renderer's Rasterize pipeline stage, into a FrameBuffer's FrameBuffer.Viewport.

    For both the perspective and the parallel projections, the camera's near plane is there to prevent the camera from seeing what is "behind" the near plane. For the perspective projection, the near plane also prevents the renderer from incorrectly rasterizing line segments that cross the camera plane, z = 0.

    • Field Detail

      • left

        public final double left
      • right

        public final double right
      • bottom

        public final double bottom
      • top

        public final double top
      • n

        public final double n
    • Method Detail

      • projPerspective

        public static Camera projPerspective()
        This is a static factory method.

        Set up this Camera's view volume as a perspective projection of the normalized infinite view pyramid extending along the negative z-axis.

        Returns:
        a new Camera object with the default perspective parameters
      • projPerspective

        public static Camera projPerspective​(double left,
                                             double right,
                                             double bottom,
                                             double top)
        This is a static factory method.

        Set up this Camera's view volume as a perspective projection of an infinite view pyramid extending along the negative z-axis.

        Parameters:
        left - left edge of view rectangle in the image plane
        right - right edge of view rectangle in the image plane
        bottom - bottom edge of view rectangle in the image plane
        top - top edge of view rectangle in the image plane
        Returns:
        a new Camera object with the given parameters
      • projPerspective

        public static Camera projPerspective​(double left,
                                             double right,
                                             double bottom,
                                             double top,
                                             double focalLength)
        This is a static factory method.

        Set up this Camera's view volume as a perspective projection of an infinite view pyramid extending along the negative z-axis.

        Use focalLength to determine the image plane. So the left, right, bottom, top parameters are used in the plane z = -focalLength.

        The focalLength parameter can be used to zoom an asymmetric view volume, much like the fovy parameter for the symmetric view volume, or the "near" parameter for the OpenGL gluPerspective() function.

        Parameters:
        left - left edge of view rectangle in the image plane
        right - right edge of view rectangle in the image plane
        bottom - bottom edge of view rectangle in the image plane
        top - top edge of view rectangle in the image plane
        focalLength - distance from the origin to the image plane
        Returns:
        a new Camera object with the given parameters
      • projPerspective

        public static Camera projPerspective​(double fovy,
                                             double aspect)
        This is a static factory method.

        Set up this Camera's view volume as a symmetric infinite view pyramid extending along the negative z-axis.

        Here, the view volume is determined by a vertical "field of view" angle and an aspect ratio for the view rectangle in the image plane.

        Parameters:
        fovy - angle in the y-direction subtended by the view rectangle in the image plane
        aspect - aspect ratio of the view rectangle in the image plane
        Returns:
        a new Camera object with the given parameters
      • projOrtho

        public static Camera projOrtho()
        This is a static factory method.

        Set up this Camera's view volume as a parallel (orthographic) projection of the normalized infinite view parallelepiped extending along the z-axis.

        Returns:
        a new Camera object with the default orthographic parameters
      • projOrtho

        public static Camera projOrtho​(double left,
                                       double right,
                                       double bottom,
                                       double top)
        This is a static factory method.

        Set up this Camera's view volume as a parallel (orthographic) projection of an infinite view parallelepiped extending along the z-axis.

        Parameters:
        left - left edge of view rectangle in the xy-plane
        right - right edge of view rectangle in the xy-plane
        bottom - bottom edge of view rectangle in the xy-plane
        top - top edge of view rectangle in the xy-plane
        Returns:
        a new Camera object with the given parameters
      • projOrtho

        public static Camera projOrtho​(double fovy,
                                       double aspect)
        This is a static factory method.

        Set up this Camera's view volume as a symmetric infinite view parallelepiped extending along the z-axis.

        Here, the view volume is determined by a vertical "field-of-view" angle and an aspect ratio for the view rectangle in the image plane.

        Parameters:
        fovy - angle in the y-direction subtended by the view rectangle in the image plane
        aspect - aspect ratio of the view rectangle in the image plane
        Returns:
        a new Camera object with the given parameters
      • changeNear

        public Camera changeNear​(double near)
        Create a new Camera that is essentially the same as this Camera but with the given distance from the camera to the near clipping plane.

        When near is positive, the near clipping plane is in front of the camera. When near is negative, the near clipping plane is behind the camera.

        Parameters:
        near - distance from the new Camera to its near clipping plane
        Returns:
        a new Camera object with the given value for near