jMonkeyEngine-wiki/docs/modules/ROOT/pages/jme3/advanced/camera.adoc

= The jME3 Camera
:author:
:revnumber:
:revdate: 2016/03/17 20:48
:keywords: camera, documentation
:relfileprefix: ../../
:imagesdir: ../..
ifdef::env-github,env-browser[:outfilesuffix: .adoc]


[NOTE]
====
By default, the mouse pointer is invisible, and the mouse is set up to control the camera rotation.
====


== Default Camera

The default com.jme3.renderer.Camera object is `cam` in com.jme3.app.Application.

The camera object is created with the following defaults:

*  Width and height are set to the current Application's settings.getWidth() and settings.getHeight() values.
*  Frustum Perspective:
**  Frame of view angle of 45° along the Y axis
**  Aspect ratio of width divided by height
**  Near view plane of 1 wu
**  Far view plane of 1000 wu

*  Start location at (0f, 0f, 10f).
*  Start direction is looking at the origin.

[cols="2", options="header"]
|===

a|Method
a|Usage

a|cam.getLocation(), setLocation()
a|The camera position

a|cam.getRotation(), setRotation()
a|The camera rotation

a|cam.getLeft(), setLeft()
a|The left axis of the camera

a|cam.getUp(), setUp()
a|The up axis of the camera, usually Vector3f(0,1,0)

a|cam.getDirection()
a|The vector the camera is facing

a|cam.getAxes(), setAxes(left,up,dir)
a|One accessor for the three properties left/up/direction.

a|cam.getFrame(), setFrame(loc,left,up,dir)
a|One accessor for the four properties location/left/up/direction.

a|cam.resize(width, height, fixAspect)
a|Resize an existing camera object while keeping all other settings. Set fixAspect to true to adjust the aspect ratio (?)

a|cam.setFrustum( near, far, left, right, top, bottom )
a|The frustum is defined by the near/far plane, left/right plane, top/bottom plane (all distances as float values)

a|cam.setFrustumPerspective( fovY, aspect ratio, near, far)
a|The frustum is defined by view angle along the Y axis (in degrees), aspect ratio, and the near/far plane.

a|cam.lookAt(target,up)
a|Turn the camera to look at Coordinate target, and rotate it around the up axis.

a|cam.setParallelProjection(false)
a|Normal perspective

a|cam.setParallelProjection(true)
a|Parallel projection perspective

a|cam.getScreenCoordinates(worldPos)
a|Converts the given position from world space to screen space.

|===

[TIP]
====
After you change view port, frustum, or frame, call `cam.update();`
====


== FlyBy Camera

The `flyCam` class field gives you access to an AppState that extends the default camera in `com.jme3.app.SimpleApplication` with more features. The input manager of the `com.jme3.input.FlyByCamera` AppState is preconfigured to respond to the WASD keys for walking forwards and backwards, and strafing to the sides; move the mouse to rotate the camera ("`Mouse Look`"), scroll the mouse wheel for zooming in or out. The QZ keys raise or lower the camera vertically.

[source]
----

Q  W             up   forw
A  S  D    -->  left  back  right
Z               down

----
[cols="2", options="header"]
|===

a|Method
a|Usage

a|flyCam.setEnabled(true);
a|Activate the flyby cam

a|flyCam.setMoveSpeed(10);
a|Control the move speed

a|flyCam.setRotationSpeed(10);
a|Control the rotation speed

a|flyCam.setDragToRotate(true)
a|Forces the player to keep mouse button pressed to rotate camera, typically used for Applets. If false (default), all mouse movement will be captured and interpreted as rotations.

|===

The FlyByCamera is active by default, but you can change all these defaults for your game.


== Chase Camera

jME3 also supports an optional Chase Cam that can follow a moving target Spatial (`com.jme3.input.ChaseCamera`). When you use the chase cam, the player clicks and hold the mouse button to rotate the camera around the camera target. You can use a chase cam if you need the mouse pointer visible in your game.

[source,java]
----

flyCam.setEnabled(false);
ChaseCamera chaseCam = new ChaseCamera(cam, target, inputManager);

----
[cols="2", options="header"]
|===

a|Method
a|Usage

a|chaseCam.setSmoothMotion(true);
a|Interpolates a smoother acceleration/deceleration when the camera moves.

a|chaseCam.setChasingSensitivity(5f)
a|The lower the chasing sensitivity, the slower the camera will follow the target when it moves.

a|chaseCam.setTrailingSensitivity(0.5f)
a|The lower the traling sensitivity, the slower the camera will begin to go after the target when it moves. Default is 0.5;

a|chaseCam.setRotationSensitivity(5f)
a|The lower the sensitivity, the slower the camera will rotate around the target when the mosue is dragged. Default is 5.

a|chaseCam.setTrailingRotationInertia(0.1f)
a|This prevents the camera to stop too abruptly when the target stops rotating before the camera has reached the target's trailing position. Default is 0.1f.

a|chaseCam.setDefaultDistance(40);
a|The default distance to the target at the start of the application.

a|chaseCam.setMaxDistance(40);
a|The maximum zoom distance. Default is 40f.

a|chaseCam.setMinDistance(1);
a|The minimum zoom distance. Default is 1f.

a|chaseCam.setMinVerticalRotation(-FastMath.PI/2);
a|The minimal vertical rotation angle of the camera around the target. Default is 0.

a|chaseCam.setDefaultVerticalRotation(-FastMath.PI/2);
a|The default vertical rotation angle of the camera around the target at the start of the application.

a|chaseCam.setDefaultHorizontalRotation(-FastMath.PI/2);
a|The default horizontal rotation angle of the camera around the target at the start of the application.

|===