java.lang.Object
- com.google.android.filament.Camera

public class Camera
extends java.lang.Object

Camera represents the eye through which the scene is viewed.

A Camera has a position and orientation and controls the projection and exposure parameters.

Creation and destruction

In Filament, Camera is a component that must be associated with an entity. To do so, use Engine.createCamera(int). A Camera component is destroyed using Engine.destroyCameraComponent(int Entity) ()}.

  Camera myCamera = engine.createCamera(myCameraEntity);
  myCamera.setProjection(45, 16.0/9.0, 0.1, 1.0);
  myCamera.lookAt(0, 1.60, 1,
                  0, 0, 0,
                  0, 1, 0);
  engine.destroyCameraComponent(myCameraEntity);

Coordinate system

The camera coordinate system defines the view space. The camera points towards its -z axis and is oriented such that its top side is in the direction of +y, and its right side in the direction of +x.

Since the near and far planes are defined by the distance from the camera, their respective coordinates are -distance_near and -distance_far.

Clipping planes

The camera defines six clipping planes which together create a clipping volume. The geometry outside this volume is clipped.

The clipping volume can either be a box or a frustum depending on which projection is used, respectively ORTHO or PERSPECTIVE. The six planes are specified either directly or indirectly using setProjection(com.google.android.filament.Camera.Projection, double, double, double, double, double, double) or setLensProjection(double, double, double, double).

The six planes are:

left
right
bottom
top
near
far

To increase the depth-buffer precision, the far clipping plane is always assumed to be at infinity for rendering. That is, it is not used to clip geometry during rendering. However, it is used during the culling phase (objects entirely behind the far plane are culled).

Choosing the near plane distance

The near plane distance greatly affects the depth-buffer resolution.

Example: Precision at 1m, 10m, 100m and 1Km for various near distances assuming a 32-bit float depth-buffer

near (m)	1 m	10 m	100 m	1 Km
0.001	7.2e-5	0.0043	0.4624	48.58
0.01	6.9e-6	0.0001	0.0430	4.62
0.1	3.6e-7	7.0e-5	0.0072	0.43
1.0	0	3.8e-6	0.0007	0.07

As can be seen in the table above, the depth-buffer precision drops rapidly with the distance to the camera.

Make sure to pick the highest near plane distance possible.

Exposure

The Camera is also used to set the scene's exposure, just like with a real camera. The lights intensity and the Camera exposure interact to produce the final scene's brightness.

See Also:: View

Nested Class Summary

Nested Classes
Modifier and Type	Class	Description
`static class`	`Camera.Fov`	Denotes a field-of-view direction.
`static class`	`Camera.Projection`	Denotes the projection type used by this camera.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method	Description
`float`	`getAperture()`	Gets the aperture in f-stops
`float`	`getCullingFar()`	Gets the distance to the far plane
`double[]`	`getCullingProjectionMatrix(double[] out)`	Retrieves the camera's culling matrix.
`int`	`getEntity()`	Gets the entity representing this Camera
`double`	`getFocalLength()`	Gets the focal length in meters
`float`	`getFocusDistance()`	Gets the distance from the camera to the focus plane in world units
`float[]`	`getForwardVector(float[] out)`	Retrieves the camera forward unit vector in world space, that is a unit vector that points in the direction the camera is looking at.
`float[]`	`getLeftVector(float[] out)`	Retrieves the camera left unit vector in world space, that is a unit vector that points to the left of the camera.
`double[]`	`getModelMatrix(double[] out)`	Retrieves the camera's model matrix.
`float[]`	`getModelMatrix(float[] out)`	Retrieves the camera's model matrix.
`long`	`getNativeObject()`
`float`	`getNear()`	Gets the distance to the near plane
`float[]`	`getPosition(float[] out)`	Retrieves the camera position in world space.
`double[]`	`getProjectionMatrix(double[] out)`	Retrieves the camera's projection matrix.
`double[]`	`getScaling(double[] out)`	Returns the scaling amount used to scale the projection matrix.
`float`	`getSensitivity()`	Gets the sensitivity in ISO
`float`	`getShutterSpeed()`	Gets the shutter speed in seconds
`float[]`	`getUpVector(float[] out)`	Retrieves the camera up unit vector in world space, that is a unit vector that points up with respect to the camera.
`double[]`	`getViewMatrix(double[] out)`	Retrieves the camera's view matrix.
`float[]`	`getViewMatrix(float[] out)`	Retrieves the camera's view matrix.
`void`	`lookAt(double eyeX, double eyeY, double eyeZ, double centerX, double centerY, double centerZ, double upX, double upY, double upZ)`	Sets the camera's view matrix.
`void`	`setCustomProjection(double[] inProjection, double[] inProjectionForCulling, double near, double far)`	Sets a custom projection matrix.
`void`	`setCustomProjection(double[] inProjection, double near, double far)`	Sets a custom projection matrix.
`void`	`setExposure(float exposure)`	Sets this camera's exposure directly.
`void`	`setExposure(float aperture, float shutterSpeed, float sensitivity)`	Sets this camera's exposure (default is f/16, 1/125s, 100 ISO) The exposure ultimately controls the scene's brightness, just like with a real camera.
`void`	`setFocusDistance(float distance)`	Set the camera focus distance in world units
`void`	`setLensProjection(double focalLength, double aspect, double near, double far)`	Sets the projection matrix from the focal length.
`void`	`setModelMatrix(double[] viewMatrix)`	Sets the camera's view matrix.
`void`	`setModelMatrix(float[] viewMatrix)`	Sets the camera's view matrix.
`void`	`setProjection(double fovInDegrees, double aspect, double near, double far, Camera.Fov direction)`	Sets the projection matrix from the field-of-view.
`void`	`setProjection(Camera.Projection projection, double left, double right, double bottom, double top, double near, double far)`	Sets the projection matrix from a frustum defined by six planes.
`void`	`setScaling(double[] inScaling)`	Deprecated. use `setScaling(double, double)`
`void`	`setScaling(double xscaling, double yscaling)`	Sets an additional matrix that scales the projection matrix.
`void`	`setShift(double xshift, double yshift)`	Sets an additional matrix that shifts (translates) the projection matrix.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Method Detail
  - setProjection
```
public void setProjection(@NonNull
                          Camera.Projection projection,
                          double left,
                          double right,
                          double bottom,
                          double top,
                          double near,
                          double far)
```
    Sets the projection matrix from a frustum defined by six planes.
    
    Parameters:
    
    projection - type of projection to use
    
    left - distance in world units from the camera to the left plane, at the near plane. Precondition: left != right
    
    right - distance in world units from the camera to the right plane, at the near plane. Precondition: left != right
    
    bottom - distance in world units from the camera to the bottom plane, at the near plane. Precondition: bottom != top
    
    top - distance in world units from the camera to the top plane, at the near plane. Precondition: bottom != top
    
    near - distance in world units from the camera to the near plane. The near plane's position in view space is z = -near. Precondition: near > 0 for Camera.Projection.PERSPECTIVE or near != far for Camera.Projection.ORTHO.
    
    far - distance in world units from the camera to the far plane. The far plane's position in view space is z = -far. Precondition: far > near for Camera.Projection.PERSPECTIVE or far != near for Camera.Projection.ORTHO.
    These parameters are silently modified to meet the preconditions above.
    
    See Also:
    
    Camera.Projection
  - setProjection
```
public void setProjection(double fovInDegrees,
                          double aspect,
                          double near,
                          double far,
                          @NonNull
                          Camera.Fov direction)
```
    Sets the projection matrix from the field-of-view.
    
    Parameters:
    
    fovInDegrees - full field-of-view in degrees. 0 < fovInDegrees < 180
    
    aspect - aspect ratio width/height. aspect > 0
    
    near - distance in world units from the camera to the near plane. The near plane's position in view space is z = -near. Precondition: near > 0 for Camera.Projection.PERSPECTIVE or near != far for Camera.Projection.ORTHO.
    
    far - distance in world units from the camera to the far plane. The far plane's position in view space is z = -far. Precondition: far > near for Camera.Projection.PERSPECTIVE or far != near for Camera.Projection.ORTHO.
    
    direction - direction of the field-of-view parameter.
    These parameters are silently modified to meet the preconditions above.
    
    See Also:
    
    Camera.Fov
  - setLensProjection
```
public void setLensProjection(double focalLength,
                              double aspect,
                              double near,
                              double far)
```
    Sets the projection matrix from the focal length.
    
    Parameters:
    
    focalLength - lens's focal length in millimeters. focalLength > 0
    
    aspect - aspect ratio width/height. aspect > 0
    
    near - distance in world units from the camera to the near plane. The near plane's position in view space is z = -near. Precondition: near > 0 for Camera.Projection.PERSPECTIVE or near != far for Camera.Projection.ORTHO.
    
    far - distance in world units from the camera to the far plane. The far plane's position in view space is z = -far. Precondition: far > near for Camera.Projection.PERSPECTIVE or far != near for Camera.Projection.ORTHO.
  - setCustomProjection
```
public void setCustomProjection(@NonNull @Size(min=16L)
                                double[] inProjection,
                                double near,
                                double far)
```
    Sets a custom projection matrix.
    The projection matrix must define an NDC system that must match the OpenGL convention, that is all 3 axis are mapped to [-1, 1].
    
    Parameters:
    
    inProjection - custom projection matrix for rendering and culling
    
    near - distance in world units from the camera to the near plane. The near plane's position in view space is z = -near. Precondition: near > 0 for Camera.Projection.PERSPECTIVE or near != far for Camera.Projection.ORTHO.
    
    far - distance in world units from the camera to the far plane. The far plane's position in view space is z = -far. Precondition: far > near for Camera.Projection.PERSPECTIVE or far != near for Camera.Projection.ORTHO.
  - setCustomProjection
```
public void setCustomProjection(@NonNull @Size(min=16L)
                                double[] inProjection,
                                @NonNull @Size(min=16L)
                                double[] inProjectionForCulling,
                                double near,
                                double far)
```
    Sets a custom projection matrix.
    The projection matrices must define an NDC system that must match the OpenGL convention, that is all 3 axis are mapped to [-1, 1].
    
    Parameters:
    
    inProjection - custom projection matrix for rendering.
    
    inProjectionForCulling - custom projection matrix for culling.
    
    near - distance in world units from the camera to the near plane. The near plane's position in view space is z = -near. Precondition: near > 0 for Camera.Projection.PERSPECTIVE or near != far for Camera.Projection.ORTHO.
    
    far - distance in world units from the camera to the far plane. The far plane's position in view space is z = -far. Precondition: far > near for Camera.Projection.PERSPECTIVE or far != near for Camera.Projection.ORTHO.
  - setScaling
```
public void setScaling(double xscaling,
                       double yscaling)
```
    Sets an additional matrix that scales the projection matrix.
    This is useful to adjust the aspect ratio of the camera independent from its projection. First, pass an aspect of 1.0 to setProjection. Then set the scaling with the desired aspect ratio:
    double aspect = width / height; // with Fov.HORIZONTAL passed to setProjection: camera.setScaling(1.0, aspect); // with Fov.VERTICAL passed to setProjection: camera.setScaling(1.0 / aspect, 1.0); By default, this is an identity matrix.
    
    Parameters:
    
    xscaling - horizontal scaling to be applied after the projection matrix.
    
    yscaling - vertical scaling to be applied after the projection matrix.
    
    See Also:
    
    setProjection(com.google.android.filament.Camera.Projection, double, double, double, double, double, double), setLensProjection(double, double, double, double), setCustomProjection(double[], double, double)
  - setScaling
```
@Deprecated
public void setScaling(@NonNull @Size(min=4L)
                       double[] inScaling)
```
    Deprecated.
    use setScaling(double, double)
    
    Sets an additional matrix that scales the projection matrix.
    This is useful to adjust the aspect ratio of the camera independent from its projection. First, pass an aspect of 1.0 to setProjection. Then set the scaling with the desired aspect ratio:
    double aspect = width / height; // with Fov.HORIZONTAL passed to setProjection: double[] s = {1.0, aspect, 1.0, 1.0}; camera.setScaling(s); // with Fov.VERTICAL passed to setProjection: double[] s = {1.0 / aspect, 1.0, 1.0, 1.0}; camera.setScaling(s); By default, this is an identity matrix.
    
    Parameters:
    
    scaling - diagonal of the scaling matrix to be applied after the projection matrix.
    
    See Also:
    
    setProjection(com.google.android.filament.Camera.Projection, double, double, double, double, double, double), setLensProjection(double, double, double, double), setCustomProjection(double[], double, double)
  - setShift
```
public void setShift(double xshift,
                     double yshift)
```
    Sets an additional matrix that shifts (translates) the projection matrix.
    The shift parameters are specified in NDC coordinates, that is, if the translation must be specified in pixels, the xshift and yshift parameters be scaled by 1.0 / viewport.width and 1.0 / viewport.height respectively.
    
    Parameters:
    
    xshift - horizontal shift in NDC coordinates applied after the projection
    
    yshift - vertical shift in NDC coordinates applied after the projection
    
    See Also:
    
    setProjection(com.google.android.filament.Camera.Projection, double, double, double, double, double, double), setLensProjection(double, double, double, double), setCustomProjection(double[], double, double)
  - setModelMatrix
```
public void setModelMatrix(@NonNull @Size(min=16L)
                           float[] viewMatrix)
```
    Sets the camera's view matrix.
    Helper method to set the camera's entity transform component. Remember that the Camera "looks" towards its -z axis.
    This has the same effect as calling:
    engine.getTransformManager().setTransform( engine.getTransformManager().getInstance(camera->getEntity()), viewMatrix);
    Parameters:
    
    viewMatrix - The camera position and orientation provided as a rigid transform matrix.
  - setModelMatrix
```
public void setModelMatrix(@NonNull @Size(min=16L)
                           double[] viewMatrix)
```
    Sets the camera's view matrix.
    Helper method to set the camera's entity transform component. Remember that the Camera "looks" towards its -z axis.
    
    Parameters:
    
    viewMatrix - The camera position and orientation provided as a rigid transform matrix.
  - lookAt
```
public void lookAt(double eyeX,
                   double eyeY,
                   double eyeZ,
                   double centerX,
                   double centerY,
                   double centerZ,
                   double upX,
                   double upY,
                   double upZ)
```
    Sets the camera's view matrix.
    
    Parameters:
    
    eyeX - x-axis position of the camera in world space
    
    eyeY - y-axis position of the camera in world space
    
    eyeZ - z-axis position of the camera in world space
    
    centerX - x-axis position of the point in world space the camera is looking at
    
    centerY - y-axis position of the point in world space the camera is looking at
    
    centerZ - z-axis position of the point in world space the camera is looking at
    
    upX - x-axis coordinate of a unit vector denoting the camera's "up" direction
    
    upY - y-axis coordinate of a unit vector denoting the camera's "up" direction
    
    upZ - z-axis coordinate of a unit vector denoting the camera's "up" direction
  - getNear
```
public float getNear()
```
    Gets the distance to the near plane
    
    Returns:
    
    Distance to the near plane
  - getCullingFar
```
public float getCullingFar()
```
    Gets the distance to the far plane
    
    Returns:
    
    Distance to the far plane
  - getProjectionMatrix
```
@NonNull
@Size(min=16L)
public double[] getProjectionMatrix(@Nullable @Size(min=16L)
                                    double[] out)
```
    Retrieves the camera's projection matrix. The projection matrix used for rendering always has its far plane set to infinity. This is why it may differ from the matrix set through setProjection() or setLensProjection().
    
    Parameters:
    
    out - A 16-float array where the projection matrix will be stored, or null in which case a new array is allocated.
    
    Returns:
    
    A 16-float array containing the camera's projection as a column-major matrix.
  - getCullingProjectionMatrix
```
@NonNull
@Size(min=16L)
public double[] getCullingProjectionMatrix(@Nullable @Size(min=16L)
                                           double[] out)
```
    Retrieves the camera's culling matrix. The culling matrix is the same as the projection matrix, except the far plane is finite.
    
    Parameters:
    
    out - A 16-float array where the projection matrix will be stored, or null in which case a new array is allocated.
    
    Returns:
    
    A 16-float array containing the camera's projection as a column-major matrix.
  - getScaling
```
@NonNull
@Size(min=4L)
public double[] getScaling(@Nullable @Size(min=4L)
                           double[] out)
```
    Returns the scaling amount used to scale the projection matrix.
    
    Returns:
    
    the diagonal of the scaling matrix applied after the projection matrix.
    
    See Also:
    
    setScaling(double, double)
  - getModelMatrix
```
@NonNull
@Size(min=16L)
public float[] getModelMatrix(@Nullable @Size(min=16L)
                              float[] out)
```
    Retrieves the camera's model matrix. The model matrix encodes the camera position and orientation, or pose.
    
    Parameters:
    
    out - A 16-float array where the model matrix will be stored, or null in which case a new array is allocated.
    
    Returns:
    
    A 16-float array containing the camera's pose as a column-major matrix.
  - getModelMatrix
```
@NonNull
@Size(min=16L)
public double[] getModelMatrix(@Nullable @Size(min=16L)
                               double[] out)
```
    Retrieves the camera's model matrix. The model matrix encodes the camera position and orientation, or pose.
    
    Parameters:
    
    out - A 16-double array where the model matrix will be stored, or null in which case a new array is allocated.
    
    Returns:
    
    A 16-double array containing the camera's pose as a column-major matrix.
  - getViewMatrix
```
@NonNull
@Size(min=16L)
public float[] getViewMatrix(@Nullable @Size(min=16L)
                             float[] out)
```
    Retrieves the camera's view matrix. The view matrix is the inverse of the model matrix.
    
    Parameters:
    
    out - A 16-float array where the model view will be stored, or null in which case a new array is allocated.
    
    Returns:
    
    A 16-float array containing the camera's view as a column-major matrix.
  - getViewMatrix
```
@NonNull
@Size(min=16L)
public double[] getViewMatrix(@Nullable @Size(min=16L)
                              double[] out)
```
    Retrieves the camera's view matrix. The view matrix is the inverse of the model matrix.
    
    Parameters:
    
    out - A 16-double array where the model view will be stored, or null in which case a new array is allocated.
    
    Returns:
    
    A 16-double array containing the camera's view as a column-major matrix.
  - getPosition
```
@NonNull
@Size(min=3L)
public float[] getPosition(@Nullable @Size(min=3L)
                           float[] out)
```
    Retrieves the camera position in world space.
    
    Parameters:
    
    out - A 3-float array where the position will be stored, or null in which case a new array is allocated.
    
    Returns:
    
    A 3-float array containing the camera's position in world units.
  - getLeftVector
```
@NonNull
@Size(min=3L)
public float[] getLeftVector(@Nullable @Size(min=3L)
                             float[] out)
```
    Retrieves the camera left unit vector in world space, that is a unit vector that points to the left of the camera.
    
    Parameters:
    
    out - A 3-float array where the left vector will be stored, or null in which case a new array is allocated.
    
    Returns:
    
    A 3-float array containing the camera's left vector in world units.
  - getUpVector
```
@NonNull
@Size(min=3L)
public float[] getUpVector(@Nullable @Size(min=3L)
                           float[] out)
```
    Retrieves the camera up unit vector in world space, that is a unit vector that points up with respect to the camera.
    
    Parameters:
    
    out - A 3-float array where the up vector will be stored, or null in which case a new array is allocated.
    
    Returns:
    
    A 3-float array containing the camera's up vector in world units.
  - getForwardVector
```
@NonNull
@Size(min=3L)
public float[] getForwardVector(@Nullable @Size(min=3L)
                                float[] out)
```
    Retrieves the camera forward unit vector in world space, that is a unit vector that points in the direction the camera is looking at.
    
    Parameters:
    
    out - A 3-float array where the forward vector will be stored, or null in which case a new array is allocated.
    
    Returns:
    
    A 3-float array containing the camera's forward vector in world units.
  - setExposure
```
public void setExposure(float aperture,
                        float shutterSpeed,
                        float sensitivity)
```
    Sets this camera's exposure (default is f/16, 1/125s, 100 ISO) The exposure ultimately controls the scene's brightness, just like with a real camera. The default values provide adequate exposure for a camera placed outdoors on a sunny day with the sun at the zenith. With the default parameters, the scene must contain at least one Light of intensity similar to the sun (e.g.: a 100,000 lux directional light) and/or an indirect light of appropriate intensity (30,000).
    
    Parameters:
    
    aperture - Aperture in f-stops, clamped between 0.5 and 64. A lower aperture value increases the exposure, leading to a brighter scene. Realistic values are between 0.95 and 32.
    
    shutterSpeed - Shutter speed in seconds, clamped between 1/25,000 and 60. A lower shutter speed increases the exposure. Realistic values are between 1/8000 and 30.
    
    sensitivity - Sensitivity in ISO, clamped between 10 and 204,800. A higher sensitivity increases the exposure. Realistic values are between 50 and 25600.
    
    See Also:
    
    LightManager, setExposure(float)
  - setExposure
```
public void setExposure(float exposure)
```
    Sets this camera's exposure directly. Calling this method will set the aperture to 1.0, the shutter speed to 1.2 and the sensitivity will be computed to match the requested exposure (for a desired exposure of 1.0, the sensitivity will be set to 100 ISO). This method is useful when trying to match the lighting of other engines or tools. Many engines/tools use unit-less light intensities, which can be matched by setting the exposure manually. This can be typically achieved by setting the exposure to 1.0.
    
    See Also:
    
    LightManager, setExposure(float, float, float)
  - getAperture
```
public float getAperture()
```
    Gets the aperture in f-stops
    
    Returns:
    
    Aperture in f-stops
  - getShutterSpeed
```
public float getShutterSpeed()
```
    Gets the shutter speed in seconds
    
    Returns:
    
    Shutter speed in seconds
  - getFocalLength
```
public double getFocalLength()
```
    Gets the focal length in meters
    
    Returns:
    
    focal length in meters [m]
  - setFocusDistance
```
public void setFocusDistance(float distance)
```
    Set the camera focus distance in world units
    
    Parameters:
    
    distance - Distance from the camera to the focus plane in world units. Must be positive and larger than the camera's near clipping plane.
  - getFocusDistance
```
public float getFocusDistance()
```
    Gets the distance from the camera to the focus plane in world units
    
    Returns:
    
    Distance from the camera to the focus plane in world units
  - getSensitivity
```
public float getSensitivity()
```
    Gets the sensitivity in ISO
    
    Returns:
    
    Sensitivity in ISO
  - getEntity
```
public int getEntity()
```
    Gets the entity representing this Camera
    
    Returns:
    
    the entity this Camera component is attached to
  - getNativeObject
```
public long getNativeObject()
```

Class Camera

Creation and destruction

Coordinate system

Clipping planes

Choosing the near plane distance

Exposure

Nested Class Summary

Method Summary

Methods inherited from class java.lang.Object

Method Detail

setProjection

setProjection

setLensProjection

setCustomProjection

setCustomProjection

setScaling

setScaling

setShift

setModelMatrix

setModelMatrix

lookAt

getNear

getCullingFar

getProjectionMatrix

getCullingProjectionMatrix

getScaling

getModelMatrix

getModelMatrix

getViewMatrix

getViewMatrix

getPosition

getLeftVector

getUpVector

getForwardVector

setExposure

setExposure

getAperture

getShutterSpeed

getFocalLength

setFocusDistance

getFocusDistance

getSensitivity

getEntity

getNativeObject