# gizhw:camera

video capture on any platform. `cameras` lists each camera by an id the platform gives and a name; `open` takes the id with the wanted size and pixel format, and the frames come in that format. Linux captures through V4L2 (gizhw:v4l2). A platform without a backend fails each call with the class and the platform named.

```gizlang
import * as Camera from "gizhw:camera";
```

## Types

### `Info`

```gizlang
type Info = { id: string; name: string; }
```

A camera: `id` opens it (its /dev/video node on Linux), `name` is the device's own name.

- `id`: `string`
- `name`: `string`

### `Wanted`

```gizlang
type Wanted = { width: i64; height: i64; format: string; }
```

What open asks for: a size in pixels and a pixel format, "nv12", "yuyv" or "mjpeg". The device can give another
size; the camera and each frame say which.

- `width`: `i64`
- `height`: `i64`
- `format`: `string`

### `Frame`

```gizlang
type Frame = { data: bytes; width: i64; height: i64; format: string; }
```

One captured frame: its bytes in `format`, `width` x `height` pixels.

- `data`: `bytes`
- `width`: `i64`
- `height`: `i64`
- `format`: `string`

### `Camera`

```gizlang
type Camera
```

An open camera: the size and format its frames have.

- `width`: `i64`
- `height`: `i64`
- `format`: `string`

## Functions

### `cameras`

```gizlang
function cameras(sys: System): Vec<Info> throws string
```

The cameras of this machine, in the order the platform lists them.

Effects: fail, io.

### `open`

```gizlang
function open(sys: System, id: string, wanted: Wanted): Camera throws string
```

The camera `id` (from `cameras`), streaming at the wanted size and format.

Effects: fail, io.

## Methods

### `Camera.frame`

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

The next frame, waiting for it.

Effects: fail, io.

### `Camera.close`

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

Stops the stream and releases the device.

Effects: fail, io.