Package com.jme3.renderer

Class Camera

java.lang.Object
com.jme3.renderer.Camera
All Implemented Interfaces:
Savable, Cloneable
public class Camera extends Object implements Savable, Cloneable
A standalone, purely mathematical class for doing camera-related computations.

Given input data such as location, orientation (direction, left, up), and viewport settings, it can compute data necessary to render objects with the graphics library. Two matrices are generated, the view matrix transforms objects from world space into eye space, while the projection matrix transforms objects from eye space into clip space.

Another purpose of the camera class is to do frustum culling operations, defined by six planes which define a 3D frustum shape, it is possible to test if an object bounded by a mathematically defined volume is inside the camera frustum, and thus to avoid rendering objects that are outside the frustum

  • Field Details

    • location

      protected Vector3f location
      Camera's location.

    • rotation

      protected Quaternion rotation
      The orientation of the camera.

    • frustumNear

      protected float frustumNear
      Distance from camera to near frustum plane.

    • frustumFar

      protected float frustumFar
      Distance from camera to far frustum plane.

    • frustumLeft

      protected float frustumLeft
      Distance from camera to left frustum plane.

    • frustumRight

      protected float frustumRight
      Distance from camera to right frustum plane.

    • frustumTop

      protected float frustumTop
      Distance from camera to top frustum plane.

    • frustumBottom

      protected float frustumBottom
      Distance from camera to bottom frustum plane.

    • coeffLeft

      protected float[] coeffLeft
      Temporary values computed in onFrustumChange that are needed if a call is made to onFrameChange.

    • coeffRight

      protected float[] coeffRight
      Temporary values computed in onFrustumChange that are needed if a call is made to onFrameChange.

    • coeffBottom

      protected float[] coeffBottom
      Temporary values computed in onFrustumChange that are needed if a call is made to onFrameChange.

    • coeffTop

      protected float[] coeffTop
      Temporary values computed in onFrustumChange that are needed if a call is made to onFrameChange.

    • viewPortLeft

      protected float viewPortLeft
      Percent value on display where horizontal viewing starts for this camera. Default is 0.

    • viewPortRight

      protected float viewPortRight
      Percent value on display where horizontal viewing ends for this camera. Default is 1.

    • viewPortTop

      protected float viewPortTop
      Percent value on display where vertical viewing ends for this camera. Default is 1.

    • viewPortBottom

      protected float viewPortBottom
      Percent value on display where vertical viewing begins for this camera. Default is 0.

    • worldPlane

      protected Plane[] worldPlane
      Array holding the planes that this camera will check for culling.

    • width

      protected int width
      The width of the viewport in pixels.

    • height

      protected int height
      The height of the viewport in pixels.

    • viewportChanged

      protected boolean viewportChanged
      True if the renderer needs to update its viewport boundaries.

    • projectionMatrixOverride

      protected Matrix4f projectionMatrixOverride
      Temporarily overrides the projection matrix.

    • viewMatrix

      protected Matrix4f viewMatrix
      Transforms world space into eye space.

    • projectionMatrix

      protected Matrix4f projectionMatrix
      Transforms eye space into clip space, unless overridden by projectionMatrixOverride.

    • viewProjectionMatrix

      protected Matrix4f viewProjectionMatrix
      Transforms world space into clip space.

    • name

      protected String name
      The camera's name.

  • Constructor Details

    • Camera

      protected Camera()
      Serialization only. Do not use.

    • Camera

      public Camera(int width, int height)
      Instantiates a new Camera object. All values of the camera are set to default.
      Parameters:
      width - the desired width (in pixels)
      height - the desired height (in pixels)

  • Method Details

    • clone

      public Camera clone()
      Overrides:
      clone in class Object

    • copyFrom

      public void copyFrom(Camera cam)
      Copies the settings of the given camera.
      Parameters:
      cam - the camera we copy the settings from

    • setName

      public void setName(String name)
      Sets the camera's name.
      Parameters:
      name - the camera's name

    • getName

      public String getName()
      Returns the camera's name.
      Returns:
      the camera's name

    • setClipPlane

      public void setClipPlane(Plane clipPlane, Plane.Side side)
      Sets a clipPlane for this camera. The clipPlane is used to recompute the projectionMatrix using the plane as the near plane This technique is known as the oblique near-plane clipping method introduced by Eric Lengyel more info here

      Note that this will work properly only if it's called on each update, and be aware that it won't work properly with the sky bucket. if you want to handle the sky bucket, look at how it's done in SimpleWaterProcessor.java

      Parameters:
      clipPlane - the plane
      side - the side the camera stands from the plane

    • setClipPlane

      public void setClipPlane(Plane clipPlane)
      Sets a clipPlane for this camera. The cliPlane is used to recompute the projectionMatrix using the plane as the near plane This technique is known as the oblique near-plane clipping method introduced by Eric Lengyel more info here

      Note that this will work properly only if it's called on each update, and be aware that it won't work properly with the sky bucket. if you want to handle the sky bucket, look at how it's done in SimpleWaterProcessor.java

      Parameters:
      clipPlane - the plane

    • resize

      public void resize(int width, int height, boolean fixAspect)
      Resizes this camera's view for the specified display size. Invoked by an associated RenderManager to notify the camera of changes to the display dimensions.
      Parameters:
      width - the new width of the display, in pixels
      height - the new height of the display, in pixels
      fixAspect - if true, recompute the camera's frustum to preserve its prior aspect ratio

    • getFrustumBottom

      public float getFrustumBottom()
      Returns the value of the bottom frustum plane.
      Returns:
      the value of the bottom frustum plane.

    • setFrustumBottom

      public void setFrustumBottom(float frustumBottom)
      Sets the value of the bottom frustum plane.
      Parameters:
      frustumBottom - the value of the bottom frustum plane.

    • getFrustumFar

      public float getFrustumFar()
      Gets the value of the far frustum plane.
      Returns:
      the value of the far frustum plane.

    • setFrustumFar

      public void setFrustumFar(float frustumFar)
      Sets the value of the far frustum plane.
      Parameters:
      frustumFar - the value of the far frustum plane.

    • getFrustumLeft

      public float getFrustumLeft()
      Gets the value of the left frustum plane.
      Returns:
      the value of the left frustum plane.

    • setFrustumLeft

      public void setFrustumLeft(float frustumLeft)
      Sets the value of the left frustum plane.
      Parameters:
      frustumLeft - the value of the left frustum plane.

    • getFrustumNear

      public float getFrustumNear()
      Gets the value of the near frustum plane.
      Returns:
      the value of the near frustum plane.

    • setFrustumNear

      public void setFrustumNear(float frustumNear)
      Sets the value of the near frustum plane.
      Parameters:
      frustumNear - the value of the near frustum plane.

    • getFrustumRight

      public float getFrustumRight()
      Gets the value of the right frustum plane.
      Returns:
      frustumRight the value of the right frustum plane.

    • setFrustumRight

      public void setFrustumRight(float frustumRight)
      Sets the value of the right frustum plane.
      Parameters:
      frustumRight - the value of the right frustum plane.

    • getFrustumTop

      public float getFrustumTop()
      Gets the value of the top frustum plane.
      Returns:
      the value of the top frustum plane.

    • setFrustumTop

      public void setFrustumTop(float frustumTop)
      Sets the value of the top frustum plane.
      Parameters:
      frustumTop - the value of the top frustum plane.

    • getFov

      public float getFov()
      Obtains field of view when the camera is in perspective mode.
      Returns:
      Frame of view angle along the Y in degrees, or 0 if the camera is in orthogonal mode.

    • setFov

      public void setFov(float fovY)
      Sets the field of view when the camera is in perspective mode. Note that this method has no effect when the camera is in orthogonal mode.
      Parameters:
      fovY - Frame of view angle along the Y in degrees. This must be greater than 0.

    • getAspect

      public float getAspect()
      Obtains the aspect ratio.
      Returns:
      Width:Height ratio.

    • getLocation

      public Vector3f getLocation()
      Retrieves the location vector of the camera.
      Returns:
      the position of the camera.
      See Also:

    • getRotation

      public Quaternion getRotation()
      Retrieves the rotation quaternion of the camera.
      Returns:
      the rotation of the camera.

    • getDirection

      public Vector3f getDirection()
      Retrieves the direction vector the camera is facing.
      Returns:
      the direction the camera is facing.
      See Also:

    • getLeft

      public Vector3f getLeft()
      Retrieves the left axis of the camera.
      Returns:
      the left axis of the camera.
      See Also:

    • getUp

      public Vector3f getUp()
      Retrieves the up axis of the camera.
      Returns:
      the up axis of the camera.
      See Also:

    • getDirection

      public Vector3f getDirection(Vector3f store)
      Retrieves the direction vector the camera is facing.
      Parameters:
      store - storage for the result (modified if not null)
      Returns:
      the direction the camera is facing.
      See Also:

    • getLeft

      public Vector3f getLeft(Vector3f store)
      Retrieves the left axis of the camera.
      Parameters:
      store - storage for the result (modified if not null)
      Returns:
      the left axis of the camera.
      See Also:

    • getUp

      public Vector3f getUp(Vector3f store)
      Retrieves the up axis of the camera.
      Parameters:
      store - storage for the result (modified if not null)
      Returns:
      the up axis of the camera.
      See Also:

    • setLocation

      public void setLocation(Vector3f location)
      Sets the position of the camera.
      Parameters:
      location - the position of the camera.

    • setRotation

      public void setRotation(Quaternion rotation)
      Sets the orientation of this camera. This will be equivalent to setting each of the axes:
      cam.setLeft(rotation.getRotationColumn(0));
      cam.setUp(rotation.getRotationColumn(1));
      cam.setDirection(rotation.getRotationColumn(2));
      Parameters:
      rotation - the rotation of this camera

    • lookAtDirection

      public void lookAtDirection(Vector3f direction, Vector3f up)
      Sets the direction the camera is facing given a direction and an up vector.
      Parameters:
      direction - the direction this camera is facing.
      up - the desired "up" direction for the camera (not null, unaffected, typically (0,1,0))

    • setAxes

      public void setAxes(Vector3f left, Vector3f up, Vector3f direction)
      Sets the axes (left, up and direction) for this camera.
      Parameters:
      left - the left axis of the camera.
      up - the up axis of the camera.
      direction - the direction the camera is facing.
      See Also:

    • setAxes

      public void setAxes(Quaternion axes)
      Uses a rotational matrix to set the axes of the camera.
      Parameters:
      axes - the matrix that defines the orientation of the camera.

    • normalize

      public void normalize()
      Normalizes the camera vectors.

    • setFrustum

      public void setFrustum(float near, float far, float left, float right, float top, float bottom)
      Sets the frustum of this camera object.
      Parameters:
      near - the near plane.
      far - the far plane.
      left - the left plane.
      right - the right plane.
      top - the top plane.
      bottom - the bottom plane.
      See Also:

    • setFrustumPerspective

      public void setFrustumPerspective(float fovY, float aspect, float near, float far)
      Defines the frustum for the camera. This frustum is defined by a viewing angle, aspect ratio, and near/far planes
      Parameters:
      fovY - Frame of view angle along the Y in degrees.
      aspect - Width:Height ratio
      near - Near view plane distance
      far - Far view plane distance

    • setFrame

      public void setFrame(Vector3f location, Vector3f left, Vector3f up, Vector3f direction)
      Sets the orientation and location of the camera.
      Parameters:
      location - the point position of the camera.
      left - the left axis of the camera.
      up - the up axis of the camera.
      direction - the facing of the camera.
      See Also:

    • lookAt

      public void lookAt(Vector3f pos, Vector3f worldUpVector)
      A convenience method for auto-setting the frame based on a world position the user desires the camera to look at. It repoints the camera towards the given position using the difference between the position and the current camera location as a direction vector and the worldUpVector to compute up and left camera vectors.
      Parameters:
      pos - where to look at in terms of world coordinates
      worldUpVector - a normalized vector indicating the up direction of the world. (typically {0, 1, 0} in jME.)

    • setFrame

      public void setFrame(Vector3f location, Quaternion axes)
      Sets the orientation and location of the camera.
      Parameters:
      location - the point position of the camera.
      axes - the orientation of the camera.

    • update

      public void update()
      Updates the camera parameters by calling onFrustumChange,onViewPortChange and onFrameChange.
      See Also:

    • getPlaneState

      public int getPlaneState()
      Returns the state of the frustum planes. So checks can be made as to which frustum plane has been examined for culling thus far.
      Returns:
      the current plane state int.

    • setPlaneState

      public void setPlaneState(int planeState)
      Sets the state to keep track of tested planes for culling.
      Parameters:
      planeState - the updated state.

    • getViewPortLeft

      public float getViewPortLeft()
      Gets the left boundary of the viewport.
      Returns:
      the left boundary of the viewport

    • setViewPortLeft

      public void setViewPortLeft(float left)
      Sets the left boundary of the viewport.
      Parameters:
      left - the left boundary of the viewport

    • getViewPortRight

      public float getViewPortRight()
      Gets the right boundary of the viewport.
      Returns:
      the right boundary of the viewport

    • setViewPortRight

      public void setViewPortRight(float right)
      Sets the right boundary of the viewport.
      Parameters:
      right - the right boundary of the viewport

    • getViewPortTop

      public float getViewPortTop()
      Gets the top boundary of the viewport.
      Returns:
      the top boundary of the viewport

    • setViewPortTop

      public void setViewPortTop(float top)
      Sets the top boundary of the viewport.
      Parameters:
      top - the top boundary of the viewport

    • getViewPortBottom

      public float getViewPortBottom()
      Gets the bottom boundary of the viewport.
      Returns:
      the bottom boundary of the viewport

    • setViewPortBottom

      public void setViewPortBottom(float bottom)
      Sets the bottom boundary of the viewport.
      Parameters:
      bottom - the bottom boundary of the viewport

    • setViewPort

      public void setViewPort(float left, float right, float bottom, float top)
      Sets the boundaries of the viewport.
      Parameters:
      left - the left boundary of the viewport (default: 0)
      right - the right boundary of the viewport (default: 1)
      bottom - the bottom boundary of the viewport (default: 0)
      top - the top boundary of the viewport (default: 1)

    • distanceToNearPlane

      public float distanceToNearPlane(Vector3f pos)
      Returns the pseudo distance from the given position to the near plane of the camera. This is used for render queue sorting.
      Parameters:
      pos - The position to compute a distance to.
      Returns:
      Distance from the near plane to the point.

    • contains

      public Camera.FrustumIntersect contains(BoundingVolume bound)
      Tests a bounding volume against the planes of the camera's frustum. The frustum's planes are set such that the normals all face in towards the viewable scene. Therefore, if the bounding volume is on the negative side of the plane is can be culled out. NOTE: This method is used internally for culling, for public usage, the plane state of the camera must be saved and restored, e.g: BoundingVolume bv;
      Camera c;
      int planeState = c.getPlaneState();
      c.setPlaneState(0);
      c.contains(bv);
      c.setPlaneState(plateState);
      Parameters:
      bound - the bound to check for culling
      Returns:
      See enums in FrustumIntersect

    • getWorldPlane

      public Plane getWorldPlane(int planeId)
      Provides access to one of the planes used for culling.
      Parameters:
      planeId - the index of the Plane to access (0→left, 1→right, 2→bottom, 3→top, 4→far, 5→near)
      Returns:
      the pre-existing instance

    • containsGui

      public boolean containsGui(BoundingVolume bound)
      Tests a bounding volume against the ortho bounding box of the camera. A bounding box spanning from 0, 0 to Width, Height. Constrained by the viewport settings on the camera.
      Parameters:
      bound - the bound to check for culling
      Returns:
      True if the camera contains the gui element bounding volume.

    • getViewMatrix

      public Matrix4f getViewMatrix()
      Provides access to the view matrix.
      Returns:
      the view matrix of the camera.

      The view matrix transforms world space into eye space. This matrix is usually defined by the position and orientation of the camera.

    • setProjectionMatrix

      public void setProjectionMatrix(Matrix4f projMatrix)
      Overrides the projection matrix used by the camera. Will use the matrix for computing the view projection matrix as well. Use null argument to return to normal functionality.
      Parameters:
      projMatrix - the desired projection matrix (unaffected) or null to cease the override

    • getProjectionMatrix

      public Matrix4f getProjectionMatrix()
      Provides access to the projection matrix.
      Returns:
      the projection matrix of the camera.

      The view projection matrix transforms eye space into clip space. This matrix is usually defined by the viewport and perspective settings of the camera.

    • updateViewProjection

      public void updateViewProjection()
      Updates the view projection matrix.

    • getViewProjectionMatrix

      public Matrix4f getViewProjectionMatrix()
      Provides access to the view projection matrix.
      Returns:
      The result of multiplying the projection matrix by the view matrix. This matrix is required for rendering an object. It is precomputed to avoid computing it every time an object is rendered.

    • isViewportChanged

      public boolean isViewportChanged()
      Tests whether the viewport (width, height, left, right, bottom, up) has been changed. This is needed in the renderer so that the proper viewport can be set-up.
      Returns:
      true if changed, otherwise false

    • clearViewportChanged

      public void clearViewportChanged()
      Clears the viewport changed flag once it has been updated inside the renderer.

    • onViewPortChange

      public void onViewPortChange()
      Called when the viewport has been changed.

    • onFrustumChange

      public void onFrustumChange()
      Updates the frustum to reflect any changes made to the planes. The new frustum values are kept in a temporary location for use when calculating the new frame. The projection matrix is updated to reflect the current values of the frustum.

    • onFrameChange

      public void onFrameChange()
      Updates the view frame of the camera.

    • isParallelProjection

      public boolean isParallelProjection()
      Determines whether the projection is parallel or perspective.
      Returns:
      true if parallel projection is enabled, false if in normal perspective mode
      See Also:

    • setParallelProjection

      public void setParallelProjection(boolean value)
      Enables/disables parallel projection.
      Parameters:
      value - true to set up this camera for parallel projection, false to enter perspective mode

    • getViewToProjectionZ

      public float getViewToProjectionZ(float viewZPos)
      Computes the z value in projection space from the z value in view space Note that the returned value goes non-linearly from 0 to 1. For more explanation of non-linear z buffer see http://www.sjbaker.org/steve/omniv/love_your_z_buffer.html
      Parameters:
      viewZPos - the z value in view space.
      Returns:
      the z value in projection space.

    • getWorldCoordinates

      public Vector3f getWorldCoordinates(Vector2f screenPos, float projectionZPos)
      Computes a position in World space given a screen position in screen space (0,0 to width, height) and a z position in projection space ( 0 to 1 non-linear). This former value is also known as the Z buffer value or non-linear depth buffer. For more explanation of non-linear Z buffer see http://www.sjbaker.org/steve/omniv/love_your_z_buffer.html

      To compute the projection space z from the view space z (distance from cam to object)

      Parameters:
      screenPos - 2d coordinate in screen space
      projectionZPos - non linear z value in projection space
      Returns:
      the position in world space.
      See Also:

    • getWorldCoordinates

      public Vector3f getWorldCoordinates(Vector2f screenPosition, float projectionZPos, Vector3f store)
      Converts the given position from screen space to world space.
      Parameters:
      screenPosition - a (2-D) location in screen space (not null)
      projectionZPos - a (non-linear) Z value in projection space
      store - storage for the result (modified if not null)
      Returns:
      a location vector (in world coordinates, either store or a new vector)
      See Also:

    • getScreenCoordinates

      public Vector3f getScreenCoordinates(Vector3f worldPos)
      Converts the given position from world space to screen space.
      Parameters:
      worldPos - a location in world coordinates (not null, unaffected)
      Returns:
      a new (3-D) location vector (in screen coordinates)
      See Also:

    • getScreenCoordinates

      public Vector3f getScreenCoordinates(Vector3f worldPosition, Vector3f store)
      Converts the given position from world space to screen space.
      Parameters:
      worldPosition - a location in world coordinates (not null, unaffected)
      store - storage for the result (modified if not null)
      Returns:
      a (3-D) location vector (in screen coordinates, either store or a new vector)
      See Also:

    • getWidth

      public int getWidth()
      Returns the display width.
      Returns:
      the width/resolution of the display.

    • getHeight

      public int getHeight()
      Returns the display height.
      Returns:
      the height/resolution of the display.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • write

      public void write(JmeExporter e) throws IOException
      Specified by:
      write in interface Savable
      Throws:
      IOException

    • read

      public void read(JmeImporter importer) throws IOException
      Specified by:
      read in interface Savable
      Throws:
      IOException