tiramisu/camera

Camera module - define viewpoints and projections for rendering.

Cameras determine how your 3D scene is viewed. Use perspective cameras for 3D games and orthographic cameras for 2D games or UI elements.

Quick Example

import gleam/option
import tiramisu/camera
import tiramisu/scene
import tiramisu/transform
import vec/vec3

// 3D perspective camera (aspect ratio calculated automatically)
let assert Ok(cam_3d) = camera.perspective(field_of_view: 75.0, near: 0.1, far: 1000.0)

scene.Camera(
  id: "main",
  camera: cam_3d,
  transform: transform.at(position: vec3.Vec3(0.0, 5.0, 10.0)),
  look_at: option.Some(vec3.Vec3(0.0, 0.0, 0.0)),
  active: True,
  viewport: option.None,
)

// 2D orthographic camera
let cam_2d = camera.camera_2d(width: 800, height: 600)

scene.Camera(
  id: "ui",
  camera: cam_2d,
  transform: transform.at(position: vec3.Vec3(0.0, 0.0, 5.0)),
  look_at: option.None,
  active: False,
  viewport: option.None,
)

Types

Camera

opaque </>

Camera configuration (perspective or orthographic projection).

Use with scene.Camera nodes to define viewpoints in your scene. Position and orientation are set via the scene.Camera node’s transform and look_at fields.

pub opaque type Camera

CameraError

</>

Validation errors for camera creation.

pub type CameraError {
  InvalidFieldOfView(Float)
  InvalidAspectRatio(Float)
  InvalidNearPlane(Float)
  InvalidFarPlane(Float)
  NearFarConflict(near: Float, far: Float)
}

Constructors

```
InvalidFieldOfView(Float)
```
Field of view must be between 0 and 180 degrees
```
InvalidAspectRatio(Float)
```
Aspect ratio must be positive
```
InvalidNearPlane(Float)
```
Near plane must be positive
```
InvalidFarPlane(Float)
```
Far plane must be positive

NearFarConflict(near: Float, far: Float)

Near plane must be less than far plane

Values

camera_2d

</>

pub fn camera_2d(width width: Int, height height: Int) -> Camera

Create a 2D camera centered at origin with world coordinates.

Useful for 2D games where (0,0) is the center of the screen.

Example

let cam = camera.camera_2d(width: 800, height: 600)
scene.Camera(
  id: "main_camera",
  camera: cam,
  transform: transform.at(position: vec3.Vec3(0.0, 0.0, 5.0)),
  look_at: option.None,
  active: True,
  viewport: option.None,
)
// (0, 0) is screen center, positive Y is up

camera_2d_screen_space

</>

pub fn camera_2d_screen_space(width: Int, height: Int) -> Camera

Create a 2D camera with screen-space coordinates (top-left origin).

Useful for UI or pixel-perfect 2D games where (0,0) is top-left corner.

Example

let cam = camera.camera_2d_screen_space(width: 800, height: 600)
scene.Camera(
  id: "ui_camera",
  camera: cam,
  transform: transform.at(position: vec3.Vec3(0.0, 0.0, 5.0)),
  look_at: option.None,
  active: True,
  viewport: option.None,
)
// (0, 0) is top-left, positive Y is down (like CSS)

camera_2d_with_bounds

</>

pub fn camera_2d_with_bounds(
  left: Float,
  right: Float,
  top: Float,
  bottom: Float,
) -> Camera

Create a 2D camera with custom bounds.

Example

let cam = camera.camera_2d_with_bounds(
  left: -100.0, right: 100.0,
  top: 75.0, bottom: -75.0,
)
scene.Camera(
  id: "game_camera",
  camera: cam,
  transform: transform.at(position: vec3.Vec3(0.0, 0.0, 5.0)),
  look_at: option.None,
  active: True,
  viewport: option.None,
)

orthographic

</>

pub fn orthographic(
  left left: Float,
  right right: Float,
  top top: Float,
  bottom bottom: Float,
  near near: Float,
  far far: Float,
) -> Camera

Create an orthographic camera (for 2D games or isometric views).

No perspective distortion - objects are the same size regardless of distance.

Example

let cam = camera.orthographic(
  left: -400.0, right: 400.0,
  top: 300.0, bottom: -300.0,
  near: 0.1, far: 1000.0,
)

perspective

</>

pub fn perspective(
  field_of_view fov: Float,
  near near: Float,
  far far: Float,
) -> Result(Camera, CameraError)

Create a perspective camera (for 3D games).

Objects further away appear smaller, like in real life. The aspect ratio is automatically calculated from the viewport or renderer dimensions at render time.

Parameters

field_of_view: Vertical FOV in degrees (typically 60-90)
near: Near clipping plane (objects closer are not rendered)
far: Far clipping plane (objects further are not rendered)

Example

let assert Ok(cam) = camera.perspective(
  field_of_view: 75.0,
  near: 0.1,
  far: 1000.0,
)