---
title: `perspectiveCamera`
description: Creates a stateful perspective camera node. FOV is in degrees for the public scene API. Matrices are stable `Float32Array` identities updated in place, so a binding set once stays fresh after `set()` / `lookAt()` calls.
---

# `perspectiveCamera`



## Import

```ts
import { perspectiveCamera, type PerspectiveCameraOptions } from "vgpu/scene";
```

## Signature

```ts
interface PerspectiveCameraOptions {
  readonly fov: number;
  readonly aspect?: number;
  readonly near?: number;
  readonly far?: number;
  readonly position?: import("vgpu/scene").Vec3Like;
  readonly target?: import("vgpu/scene").CameraVec3;
  readonly up?: import("vgpu/scene").CameraVec3;
  readonly label?: string;
}

declare function perspectiveCamera(options: PerspectiveCameraOptions): import("vgpu/scene").PerspectiveCamera;
```

## Parameters

| Param            | Type       | Required | Default     | Notes                                                           |
| ---------------- | ---------- | -------- | ----------- | --------------------------------------------------------------- |
| options.fov      | number     | ✔        | —           | Vertical field of view in degrees. Must be in `(0, 180)`.       |
| options.aspect   | number     | ✖        | `1`         | Width / height. Update on resize with `camera.set({ aspect })`. |
| options.near     | number     | ✖        | `0.1`       | Near clip plane distance. Must be positive.                     |
| options.far      | number     | ✖        | `100`       | Far clip plane distance. Must be greater than `near`.           |
| options.position | Vec3Like   | ✖        | `[0, 0, 0]` | Initial local position.                                         |
| options.target   | CameraVec3 | ✖        | —           | When given, the camera is oriented with `lookAt(target, up)`.   |
| options.up       | CameraVec3 | ✖        | `[0, 1, 0]` | Up vector used only with `target`.                              |

**Returns:** `PerspectiveCamera` — a scene node (`kind: "perspective-camera"`) with `viewProjection`, `view`, `projection`, `position`, and `worldPosition`.
**Throws:** `VGPU-SCENE-VALUE-INVALID` for out-of-range `fov`, non-positive `near`, or `far <= near`.

## Examples

```ts
import { perspectiveCamera } from "vgpu/scene";

const cam = perspectiveCamera({ fov: 45, position: [2, 2, 3], target: [0, 0, 0] });

const matrix = cam.viewProjection; // stable identity — bind once
cam.set({ fov: 60, position: [0, 2, 5] });
cam.lookAt([0, 0, 0]);
void matrix; // same array, already updated in place
```

## Notes

* Cameras are scene nodes: parent them under a `group()` rig and the view matrix accounts for the whole chain.
* `set()` accepts projection params (`fov`, `aspect`, `near`, `far`) plus every transform key from `NodeTransformValues` (see `PerspectiveCameraValues`).
* **See also:** `PerspectiveCamera`, `orthographicCamera`, `SceneCamera`, `orbitControls`.

***

# PerspectiveCamera

Class returned by `perspectiveCamera()`. Extends `SceneNode`, implements `SceneCamera`.

## Import

```ts
import type { PerspectiveCamera } from "vgpu/scene";
```

## Signature

```ts
declare class PerspectiveCamera {
  set(values: import("vgpu/scene").PerspectiveCameraValues): this;
  lookAt(target: import("vgpu/scene").Vec3Like, up?: import("vgpu/scene").Vec3Like): this;
  readonly fov: number;
  readonly aspect: number;
  readonly near: number;
  readonly far: number;
  readonly viewProjection: Float32Array;
  readonly view: Float32Array;
  readonly projection: Float32Array;
  readonly worldPosition: Float32Array;
}
```

**Returns:** Not a callable; construct with `perspectiveCamera(options)`.
**Throws:** `VGPU-SCENE-VALUE-INVALID` from `set()` on invalid projection parameters.

## Examples

```ts
import { perspectiveCamera, type PerspectiveCamera } from "vgpu/scene";

const cam: PerspectiveCamera = perspectiveCamera({ fov: 45 });
cam.set({ aspect: 16 / 9 });
```

## Notes

* Matrix getters recompute lazily; reading `viewProjection` after a transform change is always fresh.
* **See also:** `perspectiveCamera`, `PerspectiveCameraValues`, `SceneNode`.

***

# PerspectiveCameraValues

Values accepted by `PerspectiveCamera.set()`: projection parameters plus node transform keys.

## Import

```ts
import type { PerspectiveCameraValues } from "vgpu/scene";
```

## Signature

```ts
interface PerspectiveCameraValues {
  readonly fov?: number;
  readonly aspect?: number;
  readonly near?: number;
  readonly far?: number;
  readonly position?: import("vgpu/scene").Vec3Like;
  readonly rotation?: import("vgpu/scene").Vec3Like;
  readonly quaternion?: import("vgpu/scene").QuatLike;
  readonly scale?: number | import("vgpu/scene").Vec3Like;
  readonly visible?: boolean;
  readonly label?: string;
}
```

## Examples

```ts
import { perspectiveCamera } from "vgpu/scene";

perspectiveCamera({ fov: 45 }).set({ aspect: 2, position: [0, 1, 4] });
```

## Notes

* **See also:** `PerspectiveCamera`, `NodeTransformValues`.


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)