com.jme.renderer
Interface Camera

All Superinterfaces:
Savable, java.io.Serializable
All Known Implementing Classes:
AbstractCamera, JOGLCamera, LWJGLCamera

public interface Camera
extends java.io.Serializable, Savable

Camera defines an interface that encapsulates viewport management. Provided are convenience methods for setting up the view port and the camera model. The frustum is also maintained here to allow for easy frustum culling.

Author:
Mark Powell, Gregg Patton

Nested Class Summary
static class Camera.FrustumIntersect
           
 
Method Summary
 void apply()
          Apply the settings of the camera to the current graphics state.
 Camera.FrustumIntersect contains(BoundingVolume bound)
          culled tests a bounding volume against the planes of the camera's frustum.
 Vector3f getDirection()
          getDirection returns the direction the camera is facing.
 float getFrustumBottom()
          getFrustumBottom returns the value of the bottom frustum plane.
 float getFrustumFar()
          getFrustumFar gets the value of the far frustum plane.
 float getFrustumLeft()
          getFrustumLeft gets the value of the left frustum plane.
 float getFrustumNear()
          getFrustumNear gets the value of the near frustum plane.
 float getFrustumRight()
          getFrustumRight gets the value of the right frustum plane.
 float getFrustumTop()
          getFrustumTop gets the value of the top frustum plane.
 Vector3f getLeft()
          getLeft returns the left axis of the camera.
 Vector3f getLocation()
          getLocation returns the position of the camera.
 int getPlaneState()
          getPlaneState returns the state of the frustum planes.
 Vector3f getScreenCoordinates(Vector3f worldPosition)
          Convert world to screen coordinates.
 Vector3f getScreenCoordinates(Vector3f worldPosition, Vector3f store)
          Convert world to screen coordinates.
 Vector3f getUp()
          getUp returns the up axis of the camera.
 float getViewPortBottom()
          getViewPortBottom gets the bottom boundary of the viewport
 float getViewPortLeft()
          getViewPortLeft gets the left boundary of the viewport
 float getViewPortRight()
          getViewPortRight gets the right boundary of the viewport
 float getViewPortTop()
          getViewPortTop gets the top boundary of the viewport
 Vector3f getWorldCoordinates(Vector2f screenPosition, float zPos)
          Convert screen to world coordinates.
 Vector3f getWorldCoordinates(Vector2f screenPosition, float zPos, Vector3f store)
          Convert screen to world coordinates.
 boolean isParallelProjection()
           
 void lookAt(Vector3f pos, Vector3f worldUpVector)
          lookAt is a convienence method for auto-setting the frame based on a world position the user desires the camera to look at.
 void normalize()
           
 void onFrameChange()
          onFrameChange is an update callback that is activated if the frame changes.
 void onFrustumChange()
          onFrustumChange is an update callback that is activated if the frustum values change.
 void onViewPortChange()
          onViewPortChange is an update callback that is activated if the view port changes.
 void resize(int width, int height)
          Resizes this camera's view with the given width and height.
 void setAxes(Quaternion axes)
          setAxes sets the camera's orientation via a rotational matrix.
 void setAxes(Vector3f left, Vector3f up, Vector3f direction)
          setAxes sets the axes that define the camera's orientation.
 void setDirection(Vector3f direction)
          setDirection sets the direction the camera is facing.
 void setFrame(Vector3f location, Quaternion axes)
          setFrame sets the view frame of the camera by setting the location and the orientation of the camera model.
 void setFrame(Vector3f location, Vector3f left, Vector3f up, Vector3f direction)
          setFrame sets the view frame of the camera by setting the location and orientation of the camera model.
 void setFrustum(float near, float far, float left, float right, float top, float bottom)
          setFrustum defines the frustum planes of the camera.
 void setFrustumBottom(float frustumBottom)
          setFrustumBottom sets the value of the bottom frustum plane.
 void setFrustumFar(float frustumFar)
          setFrustumFar sets the value of the far frustum plane.
 void setFrustumLeft(float frustumLeft)
          setFrustumLeft sets the value of the left frustum plane.
 void setFrustumNear(float frustumNear)
          setFrustumNear sets the value of the near frustum plane.
 void setFrustumPerspective(float fovY, float aspect, float near, float far)
          setFrustumPerspective defines the frustum for the camera.
 void setFrustumRight(float frustumRight)
          setFrustumRight sets the value of the right frustum plane.
 void setFrustumTop(float frustumTop)
          setFrustumTop sets the value of the top frustum plane.
 void setLeft(Vector3f left)
          setLeft sets the left axis of the camera.
 void setLocation(Vector3f location)
          setLocation the position of the camera.
 void setParallelProjection(boolean value)
          Enable/disable parallel projection.
 void setPlaneState(int planeState)
          setPlaneState sets the state to keep track of tested planes for culling.
 void setUp(Vector3f up)
          setUp sets the up axis of the camera.
 void setViewPort(float left, float right, float bottom, float top)
          setViewPort sets the boundaries of the viewport
 void setViewPortBottom(float bottom)
          setViewPortBottom sets the bottom boundary of the viewport
 void setViewPortLeft(float left)
          setViewPortLeft sets the left boundary of the viewport
 void setViewPortRight(float right)
          setViewPortRight sets the right boundary of the viewport
 void setViewPortTop(float top)
          setViewPortTop sets the top boundary of the viewport
 void update()
          update updates the frustum viewport and frame of the camera checking for any possible change in the position or orientation of the camera.
 
Methods inherited from interface com.jme.util.export.Savable
getClassTag, read, write
 

Method Detail

getLocation

Vector3f getLocation()
getLocation returns the position of the camera.

Returns:
the position of the camera.

getDirection

Vector3f getDirection()
getDirection returns the direction the camera is facing.

Returns:
the direction this camera object is facing.

getLeft

Vector3f getLeft()
getLeft returns the left axis of the camera.

Returns:
the left axis of this camera object.

getUp

Vector3f getUp()
getUp returns the up axis of the camera.

Returns:
the up axis of this camera object.

setLocation

void setLocation(Vector3f location)
setLocation the position of the camera.

Parameters:
location - the position of the camera.

setDirection

void setDirection(Vector3f direction)
setDirection sets the direction the camera is facing.

Parameters:
direction - the new direction of the camera.

setLeft

void setLeft(Vector3f left)
setLeft sets the left axis of the camera.

Parameters:
left - the new left axis of the camera.

setUp

void setUp(Vector3f up)
setUp sets the up axis of the camera.

Parameters:
up - the new up axis of the camera.

setAxes

void setAxes(Vector3f left,
             Vector3f up,
             Vector3f direction)
setAxes sets the axes that define the camera's orientation.

Parameters:
left - the new left axis of the camera.
up - the new up axis of the camera.
direction - the new direction of the camera.

setAxes

void setAxes(Quaternion axes)
setAxes sets the camera's orientation via a rotational matrix.

Parameters:
axes - the matrix that defines the camera orientation.

setFrustum

void setFrustum(float near,
                float far,
                float left,
                float right,
                float top,
                float bottom)
setFrustum defines the frustum planes of the camera. This frustum is defined by a six-sided box.

Parameters:
near - the frustum plane closest to the eye point.
far - the frustum plane furthest from the eye point.
left - the frustum plane left of the eye point.
right - the frustum plane right of the eye point.
top - the frustum plane above the eye point.
bottom - the frustum plane below the eye point.

setFrustumPerspective

void setFrustumPerspective(float fovY,
                           float aspect,
                           float near,
                           float far)
setFrustumPerspective 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.
aspect - Width:Height ratio
near - Near view plane distance
far - Far view plane distance

getFrustumBottom

float getFrustumBottom()
getFrustumBottom returns the value of the bottom frustum plane.

Returns:
the value of the bottom frustum plane.

setFrustumBottom

void setFrustumBottom(float frustumBottom)
setFrustumBottom sets the value of the bottom frustum plane.

Parameters:
frustumBottom - the value of the bottom frustum plane.

getFrustumFar

float getFrustumFar()
getFrustumFar gets the value of the far frustum plane.

Returns:
the value of the far frustum plane.

setFrustumFar

void setFrustumFar(float frustumFar)
setFrustumFar sets the value of the far frustum plane.

Parameters:
frustumFar - the value of the far frustum plane.

getFrustumLeft

float getFrustumLeft()
getFrustumLeft gets the value of the left frustum plane.

Returns:
the value of the left frustum plane.

setFrustumLeft

void setFrustumLeft(float frustumLeft)
setFrustumLeft sets the value of the left frustum plane.

Parameters:
frustumLeft - the value of the left frustum plane.

getFrustumNear

float getFrustumNear()
getFrustumNear gets the value of the near frustum plane.

Returns:
the value of the near frustum plane.

setFrustumNear

void setFrustumNear(float frustumNear)
setFrustumNear sets the value of the near frustum plane.

Parameters:
frustumNear - the value of the near frustum plane.

getFrustumRight

float getFrustumRight()
getFrustumRight gets the value of the right frustum plane.

Returns:
frustumRight the value of the right frustum plane.

setFrustumRight

void setFrustumRight(float frustumRight)
setFrustumRight sets the value of the right frustum plane.

Parameters:
frustumRight - the value of the right frustum plane.

getFrustumTop

float getFrustumTop()
getFrustumTop gets the value of the top frustum plane.

Returns:
the value of the top frustum plane.

setFrustumTop

void setFrustumTop(float frustumTop)
setFrustumTop sets the value of the top frustum plane.

Parameters:
frustumTop - the value of the top frustum plane.

setFrame

void setFrame(Vector3f location,
              Vector3f left,
              Vector3f up,
              Vector3f direction)
setFrame sets the view frame of the camera by setting the location and orientation of the camera model.

Parameters:
location - the position of the camera.
left - the left axis of the camera.
up - the up axis of the camera.
direction - the direction the camera is facing.

setFrame

void setFrame(Vector3f location,
              Quaternion axes)
setFrame sets the view frame of the camera by setting the location and the orientation of the camera model.

Parameters:
location - the position of the camera.
axes - the matrix that defines the orientation of the camera.

update

void update()
update updates the frustum viewport and frame of the camera checking for any possible change in the position or orientation of the camera.


normalize

void normalize()

getPlaneState

int getPlaneState()
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

void setPlaneState(int planeState)
setPlaneState sets the state to keep track of tested planes for culling.

Parameters:
planeState - the updated state.

getViewPortLeft

float getViewPortLeft()
getViewPortLeft gets the left boundary of the viewport

Returns:
the left boundary of the viewport

setViewPortLeft

void setViewPortLeft(float left)
setViewPortLeft sets the left boundary of the viewport

Parameters:
left - the left boundary of the viewport

getViewPortRight

float getViewPortRight()
getViewPortRight gets the right boundary of the viewport

Returns:
the right boundary of the viewport

setViewPortRight

void setViewPortRight(float right)
setViewPortRight sets the right boundary of the viewport

Parameters:
right - the right boundary of the viewport

getViewPortTop

float getViewPortTop()
getViewPortTop gets the top boundary of the viewport

Returns:
the top boundary of the viewport

setViewPortTop

void setViewPortTop(float top)
setViewPortTop sets the top boundary of the viewport

Parameters:
top - the top boundary of the viewport

getViewPortBottom

float getViewPortBottom()
getViewPortBottom gets the bottom boundary of the viewport

Returns:
the bottom boundary of the viewport

setViewPortBottom

void setViewPortBottom(float bottom)
setViewPortBottom sets the bottom boundary of the viewport

Parameters:
bottom - the bottom boundary of the viewport

setViewPort

void setViewPort(float left,
                 float right,
                 float bottom,
                 float top)
setViewPort sets the boundaries of the viewport

Parameters:
left - the left boundary of the viewport
right - the right boundary of the viewport
bottom - the bottom boundary of the viewport
top - the top boundary of the viewport

contains

Camera.FrustumIntersect contains(BoundingVolume bound)
culled tests a bounding volume against the planes of the camera's frustum. The frustums 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. If the object should be culled (i.e. not rendered) true is returned, otherwise, false is returned.

Parameters:
bound - the bound to check for culling
Returns:
true if the bound should be culled, false otherwise.

onFrustumChange

void onFrustumChange()
onFrustumChange is an update callback that is activated if the frustum values change.


onViewPortChange

void onViewPortChange()
onViewPortChange is an update callback that is activated if the view port changes.


onFrameChange

void onFrameChange()
onFrameChange is an update callback that is activated if the frame changes.


lookAt

void lookAt(Vector3f pos,
            Vector3f worldUpVector)
lookAt is a convienence 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.)

resize

void resize(int width,
            int height)
Resizes this camera's view with the given width and height. This is similar to constructing a new camera, but reusing the same Object. Camera view dimensions are automatically set when the camera is associated with a Renderer.

Parameters:
width - the view width
height - the view height

isParallelProjection

boolean isParallelProjection()
Returns:
true if parallel projection is enable, false if in normal perspective mode
See Also:
setParallelProjection(boolean)

setParallelProjection

void setParallelProjection(boolean value)
Enable/disable parallel projection.

Parameters:
value - true to set up this camera for parallel projection is enable, false to enter normal perspective mode

getWorldCoordinates

Vector3f getWorldCoordinates(Vector2f screenPosition,
                             float zPos)
Convert screen to world coordinates.

Parameters:
screenPosition - Vector2f representing the screen position with 0,0 at the bottom left
zPos - float The z position away from the viewing plane.
Returns:
Vector3f The store vector, after storing it's result.

getWorldCoordinates

Vector3f getWorldCoordinates(Vector2f screenPosition,
                             float zPos,
                             Vector3f store)
Convert screen to world coordinates.

Parameters:
screenPosition - Vector2f representing the screen position with 0,0 at the bottom left
zPos - float The z position away from the viewing plane.
store - Vector3f The vector to store the result in.
Returns:
Vector3f The store vector, after storing it's result.

getScreenCoordinates

Vector3f getScreenCoordinates(Vector3f worldPosition)
Convert world to screen coordinates.

Parameters:
worldPosition - Vector3f representing the world position
Returns:
Vector3f Screen coordinates, with 0,0 at the bottom left.

getScreenCoordinates

Vector3f getScreenCoordinates(Vector3f worldPosition,
                              Vector3f store)
Convert world to screen coordinates.

Parameters:
worldPosition - Vector3f representing the world position
store - Vector3f The vector to store the result in.
Returns:
Vector3f The store vector, after storing it's result. Screen coordinates, with 0,0 at the bottom left.

apply

void apply()
Apply the settings of the camera to the current graphics state.

If state should be applied even if not dirty, make sure to call update() before.