Camera - Filament

Camera represents the eye(s) through which the scene is viewed. A Camera has a position and orientation and controls the projection and exposure parameters.

Overview

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.

Creation and Destruction

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

filament::Engine* engine = filament::Engine::create();

utils::Entity myCameraEntity = utils::EntityManager::get().create();
filament::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});
engine->destroyCameraComponent(myCameraEntity);

Projection Modes

Projection::PERSPECTIVE

enum

Perspective projection - objects get smaller as they are farther from the camera

Projection::ORTHO

enum

Orthonormal projection - preserves distances regardless of depth

Field of View Direction

Fov::VERTICAL

enum

The field-of-view angle is defined on the vertical axis

Fov::HORIZONTAL

enum

The field-of-view angle is defined on the horizontal axis

Projection Methods

setProjection (Frustum)

Sets the projection matrix from a frustum defined by six planes.

projection

Projection

required

Type of projection to use (PERSPECTIVE or ORTHO)

left

double

required

Distance in world units from the camera to the left plane at the near plane

right

double

required

Distance in world units from the camera to the right plane at the near plane

bottom

double

required

Distance in world units from the camera to the bottom plane at the near plane

top

double

required

Distance in world units from the camera to the top plane at the near plane

near

double

required

Distance in world units from the camera to the near plane. Must be > 0 for PERSPECTIVE or != far for ORTHO

far

double

required

Distance in world units from the camera to the far plane. Must be > near for PERSPECTIVE or != near for ORTHO

camera->setProjection(Camera::Projection::PERSPECTIVE, -1.0, 1.0, -1.0, 1.0, 0.1, 100.0);

setProjection (Field of View)

Utility to set the projection matrix from the field-of-view.

fovInDegrees

double

required

Full field-of-view in degrees. Must be between 0 and 180

aspect

double

required

Aspect ratio (width/height). Must be > 0

near

double

required

Distance in world units from the camera to the near plane. Must be > 0

far

double

default:"INFINITY"

Distance in world units from the camera to the far plane. Must be > near

direction

Fov

default:"Fov::VERTICAL"

Direction of the fovInDegrees parameter

// 45 degree vertical FOV, 16:9 aspect ratio
camera->setProjection(45.0, 16.0/9.0, 0.1, 100.0);

setLensProjection

Utility to set the projection matrix from the focal length.

focalLengthInMillimeters

double

required

Lens’s focal length in millimeters. Must be > 0

aspect

double

required

Aspect ratio (width/height). Must be > 0

near

double

required

Distance in world units from the camera to the near plane. Must be > 0

far

double

required

Distance in world units from the camera to the far plane. Must be > near

// 35mm lens
camera->setLensProjection(35.0, 16.0/9.0, 0.1, 100.0);

setCustomProjection

Sets a custom projection matrix.

projection

math::mat4

required

Custom projection matrix used for rendering and culling. Must define an NDC system matching OpenGL convention

near

double

required

Distance in world units from the camera to the near plane

far

double

required

Distance in world units from the camera to the far plane. Must not equal near

math::mat4 customProjection = ...; // Your custom matrix
camera->setCustomProjection(customProjection, 0.1, 100.0);

setCustomEyeProjection

Sets a custom projection matrix for each eye (for stereoscopic rendering).

projection

math::mat4*

required

Array of projection matrices, only the first config.stereoscopicEyeCount are read

count

size_t

required

Size of the projection matrix array. Must be >= config.stereoscopicEyeCount

projectionForCulling

math::mat4

required

Custom projection matrix for culling, must encompass both eyes

near

double

required

Distance in world units from the camera to the culling near plane. Must be > 0

far

double

required

Distance in world units from the camera to the culling far plane. Must be > near

Transform Methods

setModelMatrix

Sets the camera’s model matrix (position and orientation).

modelMatrix

math::mat4

required

The camera position and orientation provided as a rigid transform matrix. Must be a rigid transform

math::mat4 transform = math::mat4::translation(math::float3{0, 2, 5});
camera->setModelMatrix(transform);

The model matrix must be a rigid transform. The Camera “looks” towards its -z axis.

lookAt

Sets the camera’s model matrix using position, target, and up vector.

eye

math::double3

required

The position of the camera in world space

center

math::double3

required

The point in world space the camera is looking at

math::double3

default:"{0, 1, 0}"

A unit vector denoting the camera’s “up” direction

// Position camera at (0, 1.6, 5), looking at origin
camera->lookAt({0, 1.6, 5}, {0, 0, 0}, {0, 1, 0});

setEyeModelMatrix

Set the position of an eye relative to this Camera (for stereoscopic rendering).

eyeId

uint8_t

required

The index of the eye to set. Must be < config.stereoscopicEyeCount

model

math::mat4

required

The model matrix for an individual eye

// Position eyes 3cm apart
const math::mat4 leftEye  = math::mat4::translation(math::double3{-0.03, 0.0, 0.0});
const math::mat4 rightEye = math::mat4::translation(math::double3{ 0.03, 0.0, 0.0});
camera->setEyeModelMatrix(0, leftEye);
camera->setEyeModelMatrix(1, rightEye);

Exposure Settings

setExposure (Manual)

Sets this camera’s exposure (default is f/16, 1/125s, 100 ISO).

aperture

float

required

Aperture in f-stops, clamped between 0.5 and 64. Lower values increase exposure. Realistic values are between 0.95 and 32

shutterSpeed

float

required

Shutter speed in seconds, clamped between 1/25,000 and 60. Lower values increase exposure. Realistic values are between 1/8000 and 30

sensitivity

float

required

Sensitivity in ISO, clamped between 10 and 204,800. Higher values increase exposure. Realistic values are between 50 and 25600

// Outdoor sunny day settings
camera->setExposure(16.0f, 1.0f/125.0f, 100.0f);

setExposure (Direct)

Sets this camera’s exposure directly.

exposure

float

required

Direct exposure value. Sets aperture to 1.0, shutter speed to 1.2, and computes sensitivity to match

// Set exposure to match unit-less lighting
camera->setExposure(1.0f);

Query Methods

getProjectionMatrix

Returns the projection matrix used for rendering.

eyeId

uint8_t

default:"0"

The index of the eye to return the projection matrix for. Must be < config.stereoscopicEyeCount

return

math::mat4

The projection matrix used for rendering (far plane is at infinity)

math::mat4 proj = camera->getProjectionMatrix();

getCullingProjectionMatrix

Returns the projection matrix used for culling (far plane is finite).

return

math::mat4

The projection matrix set by setProjection or setLensProjection

getNear

Returns the frustum’s near plane distance.

return

double

Near plane distance in world units

getCullingFar

Returns the frustum’s far plane used for culling.

return

double

Far plane distance in world units

getModelMatrix

Returns the camera’s model matrix (world transform).

return

math::mat4

The camera’s pose in world space as a rigid transform. Parent transforms are taken into account

getViewMatrix

Returns the camera’s view matrix (inverse of the model matrix).

return

math::mat4

The view matrix

getPosition

Returns the camera’s position in world space.

return

math::double3

Camera position

getLeftVector

Returns the camera’s normalized left vector.

return

math::float3

Normalized left vector

getUpVector

Returns the camera’s normalized up vector.

return

math::float3

Normalized up vector

getForwardVector

Returns the camera’s forward vector.

return

math::float3

Forward vector (points in -z direction)

getFieldOfViewInDegrees

Returns the camera’s field of view in degrees.

direction

Fov

required

Which direction to compute the FOV for (VERTICAL or HORIZONTAL)

return

float

Field of view in degrees

getFrustum

Returns the camera’s culling Frustum in world space.

return

Frustum

The culling frustum

getEntity

Returns the entity representing this camera.

return

utils::Entity

The camera’s entity

getAperture

Returns this camera’s aperture in f-stops.

return

float

Aperture value

getShutterSpeed

Returns this camera’s shutter speed in seconds.

return

float

Shutter speed

getSensitivity

Returns this camera’s sensitivity in ISO.

return

float

ISO sensitivity

getFocalLength

Returns the focal length in meters for a 35mm camera.

return

double

Focal length in meters

Depth of Field

setFocusDistance

Sets the camera focus distance (used by Depth-of-field PostProcessing effect).

distance

float

required

Distance from the camera to the plane of focus in world units. Must be positive and larger than the near clipping plane

camera->setFocusDistance(5.0f);

getFocusDistance

Returns the focus distance in world units.

return

float

Focus distance

Utility Methods

setScaling

Sets an additional matrix that scales the projection matrix.

scaling

math::double2

required

Diagonal of the 2x2 scaling matrix to be applied after the projection matrix

const double aspect = width / height;

// With Fov::HORIZONTAL:
camera->setScaling({1.0, aspect});

// With Fov::VERTICAL:
camera->setScaling({1.0 / aspect, 1.0});

getScaling

Returns the scaling amount used to scale the projection matrix.

return

math::double4

The diagonal of the scaling matrix applied after the projection matrix

setShift

Sets an additional matrix that shifts the projection matrix.

shift

math::double2

required

x and y translation added to the projection matrix, specified in NDC coordinates

getShift

Returns the shift amount used to translate the projection matrix.

return

math::double2

The 2D translation x and y offsets applied after the projection matrix

Static Helper Methods

projection (Field of View)

Returns the projection matrix from the field-of-view.

direction

Fov

required

Direction of the fovInDegrees parameter

fovInDegrees

double

required

Full field-of-view in degrees. Must be between 0 and 180

aspect

double

required

Aspect ratio (width/height). Must be > 0

near

double

required

Distance in world units from the camera to the near plane. Must be > 0

far

double

default:"INFINITY"

Distance in world units from the camera to the far plane. Must be > near

return

math::mat4

The computed projection matrix

math::mat4 proj = Camera::projection(Camera::Fov::VERTICAL, 45.0, 16.0/9.0, 0.1, 100.0);

projection (Focal Length)

Returns the projection matrix from the focal length.

focalLengthInMillimeters

double

required

Lens’s focal length in millimeters. Must be > 0

aspect

double

required

Aspect ratio (width/height). Must be > 0

near

double

required

Distance in world units from the camera to the near plane. Must be > 0

far

double

default:"INFINITY"

Distance in world units from the camera to the far plane. Must be > near

return

math::mat4

The computed projection matrix

inverseProjection

Returns the inverse of a projection matrix.

math::mat4

required

The projection matrix to inverse

return

math::mat4

The inverse of the projection matrix

computeEffectiveFocalLength

Helper to compute the effective focal length taking into account the focus distance.

focalLength

double

required

Focal length in any unit (e.g. meters or millimeters)

focusDistance

double

required

Focus distance in same unit as focalLength

return

double

The effective focal length in same unit as focalLength

computeEffectiveFov

Helper to compute the effective field-of-view taking into account the focus distance.

fovInDegrees

double

required

Full field of view in degrees

focusDistance

double

required

Focus distance in meters

return

double

Effective full field of view in degrees

Best Practices

Choosing the Near Plane

The near plane distance greatly affects depth-buffer precision. Make sure to pick the highest near plane distance possible. Example precision at various distances for 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

Choosing the Far Plane

The far plane distance is always set internally to infinity for rendering, but is used for culling and shadowing. Keep a reasonable ratio between near and far plane distances, typically 1:100 to 1:100000.

Core Classes

Materials & Rendering

Lighting & Camera

Transform & Animation

Utilities

​Overview

​Creation and Destruction

​Projection Modes

​Field of View Direction

​Projection Methods

​setProjection (Frustum)

​setProjection (Field of View)

​setLensProjection

​setCustomProjection

​setCustomEyeProjection

​Transform Methods

​setModelMatrix

​lookAt

​setEyeModelMatrix

​Exposure Settings

​setExposure (Manual)

​setExposure (Direct)

​Query Methods

​getProjectionMatrix

​getCullingProjectionMatrix

​getNear

​getCullingFar

​getModelMatrix

​getViewMatrix

​getPosition

​getLeftVector

​getUpVector

​getForwardVector

​getFieldOfViewInDegrees

​getFrustum

​getEntity

​getAperture

​getShutterSpeed

​getSensitivity

​getFocalLength

​Depth of Field

​setFocusDistance

​getFocusDistance

​Utility Methods

​setScaling

​getScaling

​setShift

​getShift

​Static Helper Methods

​projection (Field of View)

​projection (Focal Length)

​inverseProjection

​computeEffectiveFocalLength

​computeEffectiveFov

​Best Practices

​Choosing the Near Plane

​Choosing the Far Plane

Build docs developers (and LLMs) love

Overview

Creation and Destruction

Projection Modes

Field of View Direction

Projection Methods

setProjection (Frustum)

setProjection (Field of View)

setLensProjection

setCustomProjection

setCustomEyeProjection

Transform Methods

setModelMatrix

lookAt

setEyeModelMatrix

Exposure Settings

setExposure (Manual)

setExposure (Direct)

Query Methods

getProjectionMatrix

getCullingProjectionMatrix

getNear

getCullingFar

getModelMatrix

getViewMatrix

getPosition

getLeftVector

getUpVector

getForwardVector

getFieldOfViewInDegrees

getFrustum

getEntity

getAperture

getShutterSpeed

getSensitivity

getFocalLength

Depth of Field

setFocusDistance

getFocusDistance

Utility Methods

setScaling

getScaling

setShift

getShift

Static Helper Methods

projection (Field of View)

projection (Focal Length)

inverseProjection

computeEffectiveFocalLength

computeEffectiveFov

Best Practices

Choosing the Near Plane

Choosing the Far Plane