Package com.ardor3d.renderer

Class Camera

java.lang.Object
com.ardor3d.renderer.Camera
All Implemented Interfaces:
Savable, Externalizable, Serializable
Direct Known Subclasses:
ExtendedCamera, PSSMCamera, StereoCamera, TextureProjector
public class Camera extends Object implements Savable, Externalizable
This class represents a view into a 3d scene and how that view should map to a 2D rendering surface.
See Also:

  • Field Details

    • LEFT_PLANE

      public static final int LEFT_PLANE
      LEFT_PLANE represents the left plane of the camera frustum.
      See Also:

    • RIGHT_PLANE

      public static final int RIGHT_PLANE
      RIGHT_PLANE represents the right plane of the camera frustum.
      See Also:

    • BOTTOM_PLANE

      public static final int BOTTOM_PLANE
      BOTTOM_PLANE represents the bottom plane of the camera frustum.
      See Also:

    • TOP_PLANE

      public static final int TOP_PLANE
      TOP_PLANE represents the top plane of the camera frustum.
      See Also:

    • FAR_PLANE

      public static final int FAR_PLANE
      FAR_PLANE represents the far plane of the camera frustum.
      See Also:

    • NEAR_PLANE

      public static final int NEAR_PLANE
      NEAR_PLANE represents the near plane of the camera frustum.
      See Also:

    • FRUSTUM_PLANES

      public static final int FRUSTUM_PLANES
      FRUSTUM_PLANES represents the number of planes of the camera frustum.
      See Also:

    • MAX_WORLD_PLANES

      public static final int MAX_WORLD_PLANES
      MAX_WORLD_PLANES holds the maximum planes allowed by the system.
      See Also:

    • _location

      protected final Vector3 _location
      Camera's location

    • _left

      protected final Vector3 _left
      Direction of camera's 'left'

    • _up

      protected final Vector3 _up
      Direction of 'up' for camera.

    • _direction

      protected final Vector3 _direction
      Direction the camera is facing.

    • _depthRangeNear

      protected double _depthRangeNear
      The near range for mapping depth values from normalized device coordinates to window coordinates.

    • _depthRangeFar

      protected double _depthRangeFar
      The far range for mapping depth values from normalized device coordinates to window coordinates.

    • _frustumNear

      protected double _frustumNear
      Distance from camera to near frustum plane.

    • _frustumFar

      protected double _frustumFar
      Distance from camera to far frustum plane.

    • _frustumLeft

      protected double _frustumLeft
      Distance from camera to left frustum plane.

    • _frustumRight

      protected double _frustumRight
      Distance from camera to right frustum plane.

    • _frustumTop

      protected double _frustumTop
      Distance from camera to top frustum plane.

    • _frustumBottom

      protected double _frustumBottom
      Distance from camera to bottom frustum plane.

    • _fovY

      protected double _fovY
      Convenience store for fovY. Only set during setFrustumPerspective and never used. Retrieve by getFovY(). Default is NaN.

    • _coeffLeft

      protected double[] _coeffLeft

    • _coeffRight

      protected double[] _coeffRight

    • _coeffBottom

      protected double[] _coeffBottom

    • _coeffTop

      protected double[] _coeffTop

    • _planeQuantity

      protected int _planeQuantity
      Number of camera planes used by this camera. Default is 6.

    • _viewPortLeft

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

    • _viewPortRight

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

    • _viewPortTop

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

    • _viewPortBottom

      protected double _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.

    • _matrixBuffer

      protected final FloatBuffer _matrixBuffer

    • _tempVector

      protected final Vector3 _tempVector
      Computation vector used in various operations.

    • _modelView

      protected final Matrix4 _modelView

    • _projection

      protected final Matrix4 _projection

    • _depthRangeDirty

      protected boolean _depthRangeDirty

    • _frustumDirty

      protected boolean _frustumDirty

    • _viewPortDirty

      protected boolean _viewPortDirty

    • _frameDirty

      protected boolean _frameDirty

    • _width

      protected int _width

    • _height

      protected int _height

  • Constructor Details

    • Camera

      public Camera()
      Construct a new Camera with a width and height of 100.

    • Camera

      public Camera(int width, int height)
      Construct a new Camera with the given frame width and height.
      Parameters:
      width - the width
      height - the height

    • Camera

      public Camera(Camera source)
      Construct a new camera, using the given source camera's values.
      Parameters:
      source - the source camera to copy from

  • Method Details

    • set

      public void set(Camera source)
      Copy the source camera's fields to this camera
      Parameters:
      source - the camera to copy from

    • getDepthRangeFar

      public double getDepthRangeFar()

    • setDepthRangeFar

      public void setDepthRangeFar(double depthRangeFar)
      Parameters:
      depthRangeFar - the far clipping plane for window coordinates. Should be in the range [0, 1]. Default is 1.

    • getDepthRangeNear

      public double getDepthRangeNear()

    • setDepthRangeNear

      public void setDepthRangeNear(double depthRangeNear)
      Parameters:
      depthRangeNear - the near clipping plane for window coordinates. Should be in the range [0, 1]. Default is 0.

    • getFrustumBottom

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

    • setFrustumBottom

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

    • getFrustumFar

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

    • setFrustumFar

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

    • getFrustumLeft

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

    • setFrustumLeft

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

    • getFrustumNear

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

    • setFrustumNear

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

    • getFrustumRight

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

    • setFrustumRight

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

    • getFrustumTop

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

    • setFrustumTop

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

    • getLocation

      public ReadOnlyVector3 getLocation()
      Returns:
      the current position of the camera.

    • getDirection

      public ReadOnlyVector3 getDirection()
      Returns:
      the current direction the camera is facing.

    • getLeft

      public ReadOnlyVector3 getLeft()
      Returns:
      the left axis of the camera.

    • getUp

      public ReadOnlyVector3 getUp()
      Returns:
      the up axis of the camera.

    • setLocation

      public void setLocation(ReadOnlyVector3 location)
      Parameters:
      location - the new location or position of the camera.

    • setLocation

      public void setLocation(double x, double y, double z)
      Parameters:
      x - the new x location or position of the camera.
      y - the new y location or position of the camera.
      z - the new z location or position of the camera.

    • setDirection

      public void setDirection(ReadOnlyVector3 direction)
      Sets the new direction this camera is facing. This does not change left or up axes, so make sure those vectors are properly set as well.
      Parameters:
      direction - the new direction this camera is facing.

    • setLeft

      public void setLeft(ReadOnlyVector3 left)
      Sets the new left axis of this camera. This does not change direction or up axis, so make sure those vectors are properly set as well.
      Parameters:
      left - the new left axis of this camera.

    • setUp

      public void setUp(ReadOnlyVector3 up)
      Sets the new up axis of this camera. This does not change direction or left axis, so make sure those vectors are properly set as well.
      Parameters:
      up - the new up axis of this camera.

    • setAxes

      public void setAxes(ReadOnlyVector3 left, ReadOnlyVector3 up, ReadOnlyVector3 direction)
      Parameters:
      left - the new left axis of the camera.
      up - the new up axis of the camera.
      direction - the new direction the camera is facing.

    • setAxes

      public void setAxes(ReadOnlyMatrix3 axes)
      Sets our left, up and direction values from the given rotation matrix.
      Parameters:
      axes - the matrix that defines the orientation of the camera.

    • normalize

      public void normalize()
      Ensure our up, left and direction are unit-length vectors.

    • setFrustum

      public void setFrustum(double near, double far, double left, double right, double top, double bottom)
      Sets the frustum plane values of this camera using the given values.
      Parameters:
      near - our near plane value
      far - our far plane value
      left - our left plane value
      right - our right plane value
      top - our top plane value
      bottom - our bottom plane value

    • setFrustum

      public void setFrustum(Camera source)
      Sets the frustum plane values of this camera using those of a given source camera
      Parameters:
      source - a source camera.

    • setFrustumPerspective

      public void setFrustumPerspective(double fovY, double aspect, double near, double far)
      Sets the frustum plane values of this camera using the given perspective values.
      Parameters:
      fovY - the full angle of view on the Y axis, in degrees.
      aspect - the aspect ratio of our view (generally in [0,1]). Often this is canvas width / canvas height.
      near - our near plane value
      far - our far plane value

    • getFovY

      public double getFovY()
      Accessor for the fovY value. Note that this value is only present if setFrustumPerspective was previously called.
      Returns:
      the fovY value

    • setFrame

      public void setFrame(ReadOnlyVector3 location, ReadOnlyVector3 left, ReadOnlyVector3 up, ReadOnlyVector3 direction)
      Sets the axes and location of the camera. Similar to setAxes(ReadOnlyVector3, ReadOnlyVector3, ReadOnlyVector3), but sets camera location as well.
      Parameters:
      location - the point position of the camera
      left - the left vector of the camera's orientation
      up - the up vector of the camera's orientation
      direction - the direction vector of the camera's orientation

    • setFrame

      public void setFrame(ReadOnlyVector3 location, ReadOnlyMatrix3 axes)
      Sets the axes and location of the camera. Similar to setAxes(ReadOnlyMatrix3), but sets camera location as well.
      Parameters:
      location - the point position of the camera.
      axes - the orientation of the camera.

    • setFrame

      public void setFrame(Camera source)
      Sets the axes and location of the camera using those of a given source camera
      Parameters:
      source - a source camera.

    • lookAt

      public void lookAt(ReadOnlyVector3 pos, ReadOnlyVector3 worldUpVector)
      A convenience method for auto-setting the frame based on a world position the user desires the camera to look at. It points the camera towards the given position using the difference between that position and the current camera location as a direction vector and the general 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. (often Vector3.UNIT_Y or Vector3.UNIT_Z)

    • lookAt

      public void lookAt(double x, double y, double z, ReadOnlyVector3 worldUpVector)
      A convenience method for auto-setting the frame based on a world position the user desires the camera to look at. It points the camera towards the given position using the difference between that position and the current camera location as a direction vector and the general worldUpVector to compute up and left camera vectors.
      Parameters:
      x - where to look at in terms of world coordinates (x)
      y - where to look at in terms of world coordinates (y)
      z - where to look at in terms of world coordinates (z)
      worldUpVector - a normalized vector indicating the up direction of the world. (often Vector3.UNIT_Y or Vector3.UNIT_Z)

    • update

      public void update()
      Forces all aspect of the camera to be updated from internal values, and sets all dirty flags to true so that the next apply() call will fully set this camera to the render context.

    • getPlaneState

      public int getPlaneState()
      Returns:
      an internally used bitmask describing what frustum planes have been examined for culling thus far.

    • setPlaneState

      public void setPlaneState(int planeState)
      Parameters:
      planeState - a new value for planeState.
      See Also:

    • getViewPortLeft

      public double getViewPortLeft()
      Returns:
      the left boundary of the viewport

    • setViewPortLeft

      public void setViewPortLeft(double left)
      Parameters:
      left - the new left boundary of the viewport

    • getViewPortRight

      public double getViewPortRight()
      Returns:
      the right boundary of the viewport

    • setViewPortRight

      public void setViewPortRight(double right)
      Parameters:
      right - the new right boundary of the viewport

    • getViewPortTop

      public double getViewPortTop()
      Returns:
      the top boundary of the viewport

    • setViewPortTop

      public void setViewPortTop(double top)
      Parameters:
      top - the new top boundary of the viewport

    • getViewPortBottom

      public double getViewPortBottom()
      Returns:
      the bottom boundary of the viewport

    • setViewPortBottom

      public void setViewPortBottom(double bottom)
      Parameters:
      bottom - the new bottom boundary of the viewport

    • setViewPort

      public void setViewPort(double left, double right, double bottom, double top)
      Sets the boundaries of this camera's viewport to the given values
      Parameters:
      left - the new left boundary of the viewport
      right - the new right boundary of the viewport
      bottom - the new bottom boundary of the viewport
      top - the new top boundary of the viewport

    • contains

      public Camera.FrustumIntersect contains(BoundingVolume bound)
      Checks a bounding volume against the planes of this camera's frustum and returns if it is completely inside of, outside of, or intersecting.
      Parameters:
      bound - the bound to check for culling
      Returns:
      intersection type

    • resize

      public void resize(int width, int height)
      Resizes this camera's view with the given width and height.
      Parameters:
      width - the view width
      height - the view height

    • onFrustumChange

      public void onFrustumChange()
      Updates internal frustum coefficient values to reflect the current frustum plane values.

    • onFrameChange

      public void onFrameChange()
      Updates the values of the world planes associated with this camera.

    • updateProjectionMatrix

      protected void updateProjectionMatrix()
      Updates the value of our projection matrix.

    • setProjectionMatrix

      public void setProjectionMatrix(ReadOnlyMatrix4 projection)

    • getProjectionMatrix

      public ReadOnlyMatrix4 getProjectionMatrix()
      Returns:
      this camera's 4x4 projection matrix.

    • updateModelViewMatrix

      protected void updateModelViewMatrix()
      Updates the value of our model view matrix.

    • getModelViewMatrix

      public ReadOnlyMatrix4 getModelViewMatrix()
      Returns:
      this camera's 4x4 model view matrix.

    • getModelViewProjectionMatrix

      public ReadOnlyMatrix4 getModelViewProjectionMatrix()
      Returns:
      this camera's 4x4 model view X projection matrix.

    • getModelViewProjectionInverseMatrix

      public ReadOnlyMatrix4 getModelViewProjectionInverseMatrix()
      Returns:
      the inverse of this camera's 4x4 model view X projection matrix.

    • getPickRay

      public Ray3 getPickRay(ReadOnlyVector2 screenPosition, boolean flipVertical, Ray3 store)
      Calculate a Pick Ray using the given screen position at the near plane of this camera and the camera's position in space.
      Parameters:
      screenPosition - the x, y position on the near space to pass the ray through.
      flipVertical - if true, we'll flip the screenPosition on the y axis. This is useful when you are dealing with non-opengl coordinate systems.
      store - the Ray to store the result in. If false, a new Ray is created and returned.
      Returns:
      the resulting Ray.

    • getWorldCoordinates

      public Vector3 getWorldCoordinates(ReadOnlyVector2 screenPosition, double zDepth)
      Converts a local x,y screen position and depth value to world coordinates based on the current settings of this camera.
      Parameters:
      screenPosition - the x,y coordinates of the screen position
      zDepth - the depth into the camera view to take our point. 0 indicates the near plane of the camera and 1 indicates the far plane.
      Returns:
      a new vector containing the world coordinates.

    • getWorldCoordinates

      public Vector3 getWorldCoordinates(ReadOnlyVector2 screenPosition, double zDepth, Vector3 store)
      Converts a local x,y screen position and depth value to world coordinates based on the current settings of this camera.
      Parameters:
      screenPosition - the x,y coordinates of the screen position
      zDepth - the depth into the camera view to take our point. 0 indicates the near plane of the camera and 1 indicates the far plane.
      store - Use to avoid object creation. if not null, the results are stored in the given vector and returned. Otherwise, a new vector is created.
      Returns:
      a vector containing the world coordinates.

    • getScreenCoordinates

      public Vector3 getScreenCoordinates(ReadOnlyVector3 worldPos)
      Converts a position in world coordinate space to an x,y screen position and depth value using the current settings of this camera.
      Parameters:
      worldPos - the position in space to retrieve screen coordinates for.
      Returns:
      a new vector containing the screen coordinates as x and y and the distance as a percent between near and far planes.

    • getScreenCoordinates

      public Vector3 getScreenCoordinates(ReadOnlyVector3 worldPosition, Vector3 store)
      Converts a position in world coordinate space to an x,y screen position and depth value using the current settings of this camera.
      Parameters:
      worldPosition - the position in space to retrieve screen coordinates for.
      store - Use to avoid object creation. if not null, the results are stored in the given vector and returned. Otherwise, a new vector is created.
      Returns:
      a vector containing the screen coordinates as x and y and the distance as a percent between near and far planes.

    • getFrustumCoordinates

      public Vector3 getFrustumCoordinates(ReadOnlyVector3 worldPos)
      Converts a position in world coordinate space to a x,y,z frustum position using the current settings of this camera.
      Parameters:
      worldPos - the position in space to retrieve frustum coordinates for.
      Returns:
      a new vector containing the x,y,z frustum position

    • getFrustumCoordinates

      public Vector3 getFrustumCoordinates(ReadOnlyVector3 worldPosition, Vector3 store)
      Converts a position in world coordinate space to a x,y,z frustum position using the current settings of this camera.
      Parameters:
      worldPosition - the position in space to retrieve frustum coordinates for.
      store - Use to avoid object creation. if not null, the results are stored in the given vector and returned. Otherwise, a new vector is created.
      Returns:
      a vector containing the x,y,z frustum position

    • getNormalizedDeviceCoordinates

      public Vector3 getNormalizedDeviceCoordinates(ReadOnlyVector3 worldPos)

    • getNormalizedDeviceCoordinates

      public Vector3 getNormalizedDeviceCoordinates(ReadOnlyVector3 worldPosition, Vector3 store)

    • getHeight

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

    • getProjectionMode

      public Camera.ProjectionMode getProjectionMode()

    • setProjectionMode

      public void setProjectionMode(Camera.ProjectionMode projectionMode)

    • getWidth

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

    • apply

      public void apply(Renderer renderer)
      Apply this camera's values to the given Renderer. Only values determined to be dirty (via updates, setters, etc.) will be applied. This method must be run in the same thread as a valid OpenGL context.
      Parameters:
      renderer - the Renderer to use.

    • onViewPortChange

      protected void onViewPortChange()
      Mark view port dirty.

    • applyProjectionMatrix

      protected void applyProjectionMatrix(Renderer renderer)
      Apply the camera's projection matrix using the given Renderer.
      Parameters:
      renderer - the Renderer to use.

    • applyViewport

      protected void applyViewport(Renderer renderer)
      Apply the camera's viewport using the given Renderer.
      Parameters:
      renderer - the Renderer to use.

    • applyModelViewMatrix

      protected void applyModelViewMatrix(Renderer renderer)
      Apply the camera's modelview matrix using the given Renderer.
      Parameters:
      renderer - the Renderer to use.

    • write

      public void write(OutputCapsule capsule) throws IOException
      Specified by:
      write in interface Savable
      Throws:
      IOException

    • read

      public void read(InputCapsule capsule) throws IOException
      Specified by:
      read in interface Savable
      Throws:
      IOException

    • readExternal

      public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException
      Specified by:
      readExternal in interface Externalizable
      Throws:
      IOException
      ClassNotFoundException

    • writeExternal

      public void writeExternal(ObjectOutput out) throws IOException
      Specified by:
      writeExternal in interface Externalizable
      Throws:
      IOException

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getClassTag

      public Class<? extends Camera> getClassTag()
      Specified by:
      getClassTag in interface Savable

    • getCurrentCamera

      public static Camera getCurrentCamera()
      Convenience method for retrieving the Camera set on the current RenderContext. Similar to ContextManager.getCurrentContext().getCurrentCamera() but with null checks for current context.
      Returns:
      the Camera on the current RenderContext.

    • isFrameDirty

      public boolean isFrameDirty()