<a id="tecs.gfx.camera3d"></a>
# `tecs.gfx.camera3d`

A perspective camera maps a right-handed 3D world to one viewport.

World +X points right, +Y points up, and the default camera looks along -Z.
The camera orientation is a quaternion in `(x, y, z, w)` order that turns
camera-local coordinates into world coordinates. Position and orientation are
caller-writable fields:

```nupp
const camera = tecs.gfx.newCamera3D({
    x = 0,
    y = 2,
    z = 6,
    verticalFov = math.rad(60),
})
camera.rotationY = math.sin(math.rad(15) * 0.5)
camera.rotationW = math.cos(math.rad(15) * 0.5)
```

`matrix` writes a column-major world-to-clip matrix with depth in `[0, 1]`,
and `inverseMatrix` writes its clip-to-world inverse. `matrices` writes both
from one camera calculation for code that needs the pair. Each result uses a
separate camera-owned sixteen-float array and remains valid until that same
result is written again.

## Constructors

<a id="tecs.gfx.camera3d.newCamera3D"></a>
### `newCamera3D` _constructor_

```nupp
function newCamera3D(options: Options?): Camera3D
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `options` | `Options?` |  |

#### Returns

| Type | Description |
| --- | --- |
| `Camera3D` |  |

## Types

<a id="tecs.gfx.camera3d.Camera3D"></a>
### `Camera3D` _record_

```nupp
record Camera3D
    x: number = 0
    y: number = 0
    z: number = 0
    rotationX: number = 0
    rotationY: number = 0
    rotationZ: number = 0
    rotationW: number = 1
    verticalFov: number = 1.0471975511965976
    near: number = 0.1
    far: number = 1000
    matrix: function(exclusive self: Camera3D, width: number, height: number): {[integer]: number}
    inverseMatrix: function(exclusive self: Camera3D, width: number, height: number): {[integer]: number}
    matrices: function(
        exclusive self: Camera3D,
        width: number,
        height: number
    ): ({[integer]: number}, {[integer]: number})
end
```

Represents one perspective view into a right-handed 3D world.

#### Methods

<a id="tecs.gfx.camera3d.Camera3D.matrix"></a>
##### `matrix`

```nupp
matrix: function(exclusive self: Camera3D, width: number, height: number): {[integer]: number}
```

Writes the column-major world-to-clip matrix for a viewport.

The method normalizes the camera quaternion while calculating the view,
without modifying the caller's fields. Clip depth maps `near` to zero
and `far` to one.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive self` | `Camera3D` |  |
| `width` | `number` | The positive viewport width in pixels. |
| `height` | `number` | The positive viewport height in pixels. |

###### Returns

| Type | Description |
| --- | --- |
| `{\[integer\]: number}` | The camera's own sixteen-float array, valid until the next call on this camera. |

<a id="tecs.gfx.camera3d.Camera3D.inverseMatrix"></a>
##### `inverseMatrix`

```nupp
inverseMatrix: function(exclusive self: Camera3D, width: number, height: number): {[integer]: number}
```

Writes the column-major clip-to-world matrix for a viewport.

This is the exact inverse of `matrix` at the same dimensions. Clip x
and y range from negative one to one, clip z ranges from zero to one,
and the caller divides the resulting xyz by w.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive self` | `Camera3D` |  |
| `width` | `number` | The positive viewport width in pixels. |
| `height` | `number` | The positive viewport height in pixels. |

###### Returns

| Type | Description |
| --- | --- |
| `{\[integer\]: number}` | The camera's own sixteen-float array, valid until the next call to `inverseMatrix` on this camera. |

<a id="tecs.gfx.camera3d.Camera3D.matrices"></a>
##### `matrices`

```nupp
matrices: function(
    exclusive self: Camera3D,
    width: number,
    height: number
): ({[integer]: number}, {[integer]: number})
```

Writes the world-to-clip matrix and its clip-to-world inverse.

This method normalizes the camera quaternion and derives the projection
once, then writes both arrays. Use it when both matrices describe the
same view.

###### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `exclusive self` | `Camera3D` |  |
| `width` | `number` | The positive viewport width in pixels. |
| `height` | `number` | The positive viewport height in pixels. |

###### Returns

| Type | Description |
| --- | --- |
| `{\[integer\]: number}` | The camera's own world-to-clip sixteen-float array, valid until the next call to `matrix` or `matrices` on this camera. |
| `{\[integer\]: number}` | The camera's own clip-to-world sixteen-float array, valid until the next call to `inverseMatrix` or `matrices` on this camera. |

#### Fields

<a id="tecs.gfx.camera3d.Camera3D.x"></a>
##### `x`

```nupp
x: number
```

Caller-writable. Sets the world-space x coordinate.

<a id="tecs.gfx.camera3d.Camera3D.y"></a>
##### `y`

```nupp
y: number
```

Caller-writable. Sets the world-space y coordinate.

<a id="tecs.gfx.camera3d.Camera3D.z"></a>
##### `z`

```nupp
z: number
```

Caller-writable. Sets the world-space z coordinate.

<a id="tecs.gfx.camera3d.Camera3D.rotationX"></a>
##### `rotationX`

```nupp
rotationX: number
```

Caller-writable. Sets the local-to-world orientation quaternion x
component.

<a id="tecs.gfx.camera3d.Camera3D.rotationY"></a>
##### `rotationY`

```nupp
rotationY: number
```

Caller-writable. Sets the local-to-world orientation quaternion y
component.

<a id="tecs.gfx.camera3d.Camera3D.rotationZ"></a>
##### `rotationZ`

```nupp
rotationZ: number
```

Caller-writable. Sets the local-to-world orientation quaternion z
component.

<a id="tecs.gfx.camera3d.Camera3D.rotationW"></a>
##### `rotationW`

```nupp
rotationW: number
```

Caller-writable. Sets the local-to-world orientation quaternion scalar
component.

<a id="tecs.gfx.camera3d.Camera3D.verticalFov"></a>
##### `verticalFov`

```nupp
verticalFov: number
```

Caller-writable. Sets the vertical field of view in radians between
zero and pi.

<a id="tecs.gfx.camera3d.Camera3D.near"></a>
##### `near`

```nupp
near: number
```

Caller-writable. Sets the positive near-plane distance.

<a id="tecs.gfx.camera3d.Camera3D.far"></a>
##### `far`

```nupp
far: number
```

Caller-writable. Sets the far-plane distance, which must exceed `near`.

<a id="tecs.gfx.camera3d.Options"></a>
### `Options` _type_

```nupp
type Options = {
    --- Caller-writable. Sets the world-space x coordinate and defaults to zero.
    x: number?,

    --- Caller-writable. Sets the world-space y coordinate and defaults to zero.
    y: number?,

    --- Caller-writable. Sets the world-space z coordinate and defaults to zero.
    z: number?,

    --- Caller-writable. Sets the orientation quaternion x component and
    --- defaults to zero.
    rotationX: number?,

    --- Caller-writable. Sets the orientation quaternion y component and
    --- defaults to zero.
    rotationY: number?,

    --- Caller-writable. Sets the orientation quaternion z component and
    --- defaults to zero.
    rotationZ: number?,

    --- Caller-writable. Sets the orientation quaternion scalar component and
    --- defaults to one.
    rotationW: number?,

    --- Caller-writable. Sets the vertical field of view in radians and
    --- defaults to pi divided by three.
    verticalFov: number?,

    --- Caller-writable. Sets the positive near-plane distance and defaults to
    --- 0.1 world units.
    near: number?,

    --- Caller-writable. Sets the far-plane distance and defaults to 1000 world units.
    far: number?
}
```

Defines optional perspective-camera construction values.