# gizlang/camera

a webcam through Video4Linux 2 (/dev/videoN), on Linux and on GizOS. A camera is opened at a size it offers, in YUYV, NV12 or Motion JPEG; frame() gives the next picture as RGBA. Frames stream through buffers the driver maps (Linux's way); a driver that maps none (GizOS's UVC driver) is read with read().

```gizlang
import * as Camera from "gizlang/camera";
```

## Types

### `Size`

```gizlang
type Size = { width: i64; height: i64; }
```

A camera's size in pixels.

- `width`: `i64`
- `height`: `i64`

### `Device`

```gizlang
type Device = { path: string; name: string; }
```

A camera the system has: its device path and name.

- `path`: `string`
- `name`: `string`

### `Camera`

```gizlang
type Camera = { native: Native; fd: i64; width: i64; height: i64; format: u64; at: u64; maps: Vec<u64>; lengths: Vec<i64>; streaming: bool; }
```

An open camera: its size and format, and its buffers (mapped, or none for read()).

- `native`: `gizlang_native.Native`
- `fd`: `i64`
- `width`: `i64`
- `height`: `i64`
- `format`: `u64`
- `at`: `u64`
- `maps`: `Vec<u64>`
- `lengths`: `Vec<i64>`
- `streaming`: `bool`

### `Feed`

```gizlang
type Feed = { pictures: Task.Channel<Bitmap>; stops: Task.Channel<bool>; width: i64; height: i64; name: string; }
```

A camera read on a thread of its own: its latest pictures come on `pictures` (a slow reader misses some, never
waits), until stop.

- `pictures`: `gizlang_task.Channel<gizlang_graphics.Bitmap>`
- `stops`: `gizlang_task.Channel<bool>`
- `width`: `i64`
- `height`: `i64`
- `name`: `string`

## Functions

### `devices`

```gizlang
function devices(): Vec<Device>
```

The cameras of the system: each /dev/videoN that captures video, with its card's name.

Effects: fail, io, alloc.

### `sizes`

```gizlang
function sizes(path: string, format: u64): Vec<Size>
```

The sizes the camera at PATH gives in FORMAT, largest first.

Effects: fail, io, alloc.

### `open`

```gizlang
function open(path: string, width: i64, height: i64): Camera throws string
```

The camera at PATH, giving pictures of about WIDTH x HEIGHT (the nearest size it offers), YUYV where it can, else
NV12, else Motion JPEG (the raw formats cost no decoding). Throws why it cannot: no device, held by another
program, or no format this reads.

Effects: fail, io, alloc.

### `openDevice`

```gizlang
function openDevice(fd: i64, width: i64, height: i64): Camera throws string
```

The camera open on FD (a /dev/videoN, which another process may have opened and handed over), as open gives it; the
camera owns FD and closes it, also when this throws.

Effects: fail, io, alloc.

### `watch`

```gizlang
function watch(path: string, width: i64, height: i64): Feed throws string
```

The camera at PATH ("": the first the system has) at about WIDTH x HEIGHT, read on a thread of its own; throws why it
cannot open.

Effects: fail, read, write, console, io, alloc.

### `watchDevice`

```gizlang
function watchDevice(fd: i64, name: string, width: i64, height: i64): Feed throws string
```

The camera open on FD, named NAME, as watch gives it; the feed owns FD.

Effects: fail, read, write, console, io, alloc.

## Methods

### `Camera.frame`

```gizlang
function Camera.frame(self: Camera): Bitmap throws string
```

The camera's next picture, as RGBA; waits for it. Throws when the camera stops giving pictures.

Effects: fail, read, write, console, io, alloc.

### `Camera.picture`

```gizlang
function Camera.picture(self: Camera, data: bytes): Bitmap throws string
```

DATA, one picture in the camera's format, as RGBA.

Effects: fail, read, write, console, io, alloc.

### `Camera.close`

```gizlang
function Camera.close(self: Camera): void
```

Stops the camera and closes it.

Effects: fail, io, alloc.

### `Feed.latest`

```gizlang
function Feed.latest(self: Feed): Option<Bitmap>
```

The latest picture that came, if any since the last call.

Effects: fail, write, io, alloc.

### `Feed.stop`

```gizlang
function Feed.stop(self: Feed): void
```

Stops the thread and closes the camera.

Effects: fail, io, alloc.

## Constants

### `YUYV`

```gizlang
const YUYV = 0x56595559u
```

The pixel formats a camera may give.

### `MJPEG`

```gizlang
const MJPEG = 0x47504a4du
```

Motion JPEG: each frame is a JPEG picture.

### `NV12`

```gizlang
const NV12 = 0x3231564eu
```

NV12: a plane of luma, then one of interleaved chroma at half the resolution.

