# gizhw:v4l2

the Linux backend of gizhw:camera. Video capture devices (V4L2, /dev/videoN): the capability and formats, and streaming through buffers the kernel maps. The ioctl numbers and the layouts are the kernel's (linux/videodev2.h, checked against it). Every call is on a Handle of gizhw:device.

```gizlang
import * as V4l2 from "gizhw:v4l2";
```

## Types

### `Capability`

```gizlang
type Capability = { driver: string; card: string; bus: string; version: i64; capabilities: i64; deviceCaps: i64; }
```

A device's capability: its driver and card names, bus, version and capability bits.

- `driver`: `string`
- `card`: `string`
- `bus`: `string`
- `version`: `i64`
- `capabilities`: `i64`
- `deviceCaps`: `i64`

### `FormatDesc`

```gizlang
type FormatDesc = { index: i64; description: string; fourcc: i64; flags: i64; }
```

One format a capture device offers: its index, description, fourcc code, and flags.

- `index`: `i64`
- `description`: `string`
- `fourcc`: `i64`
- `flags`: `i64`

### `Format`

```gizlang
type Format = { width: i64; height: i64; fourcc: i64; bytesPerLine: i64; sizeImage: i64; }
```

A capture format: width and height in pixels, fourcc code, bytes per line and the size of one frame.

- `width`: `i64`
- `height`: `i64`
- `fourcc`: `i64`
- `bytesPerLine`: `i64`
- `sizeImage`: `i64`

### `Camera`

```gizlang
type Camera = { handle: Device.Handle; buffers: Vec<u64>; lengths: Vec<i64>; format: Format; }
```

An open capture stream: the handle, each buffer's mapped address and length, and the format the device set.

- `handle`: `M7.Handle`
- `buffers`: `Vec<u64>`
- `lengths`: `Vec<i64>`
- `format`: `M17.Format`

### `Buffer`

```gizlang
type Buffer = { index: i64; bytesUsed: i64; sequence: i64; offset: i64; length: i64; }
```

A buffer the kernel reports: its index, bytes used by the frame, sequence number, and its mapping (offset and length).

- `index`: `i64`
- `bytesUsed`: `i64`
- `sequence`: `i64`
- `offset`: `i64`
- `length`: `i64`

## Functions

### `parseCapability`

```gizlang
function parseCapability(data: bytes): Capability
```

The capability from the reply to VIDIOC_QUERYCAP.

Effects: fail.

### `fmtDescRequest`

```gizlang
function fmtDescRequest(index: i64): bytes
```

The request for VIDIOC_ENUM_FMT: the format at `index` of the capture type.

Effects: fail.

### `parseFmtDesc`

```gizlang
function parseFmtDesc(data: bytes): FormatDesc
```

The format the reply to VIDIOC_ENUM_FMT describes.

Effects: fail.

### `formatRequest`

```gizlang
function formatRequest(width: i64, height: i64, fourcc: i64): bytes
```

The request for VIDIOC_S_FMT: a capture format of the given size and fourcc, fields in no order.

Effects: fail.

### `parseFormat`

```gizlang
function parseFormat(data: bytes): Format
```

The format the reply to VIDIOC_S_FMT holds (the driver may change the size it was asked for).

Effects: fail.

### `requestBuffersRequest`

```gizlang
function requestBuffersRequest(count: i64): bytes
```

The request for VIDIOC_REQBUFS: `count` mmap buffers of the capture type.

Effects: fail.

### `parseRequestBuffers`

```gizlang
function parseRequestBuffers(data: bytes): i64
```

The number of buffers the driver granted (the reply to VIDIOC_REQBUFS).

Effects: fail.

### `bufferRequest`

```gizlang
function bufferRequest(index: i64): bytes
```

The request for a buffer: VIDIOC_QUERYBUF fills it, VIDIOC_QBUF and DQBUF use it. `index` is the buffer.

Effects: fail.

### `parseBuffer`

```gizlang
function parseBuffer(data: bytes): Buffer
```

The buffer from the reply to a buffer request.

Effects: fail.

### `streamType`

```gizlang
function streamType(): bytes
```

The 4-byte argument of VIDIOC_STREAMON and STREAMOFF: the capture buffer type.

Effects: fail.

### `capability`

```gizlang
function capability(h: Device.Handle): Capability throws string
```

The capability of the capture device behind `h`.

Effects: fail, io.

### `formats`

```gizlang
function formats(h: Device.Handle): Vec<FormatDesc>
```

Every format the capture device offers, in its order.

Effects: fail, io.

### `setFormat`

```gizlang
function setFormat(h: Device.Handle, width: i64, height: i64, fourcc: i64): Format throws string
```

Asks the device for a capture format; gives the format it set.

Effects: fail, io.

### `open`

```gizlang
function open(sys: System, node: string, width: i64, height: i64, fourcc: i64, count: i64): Camera throws string
```

The camera behind `node` (/dev/videoN): streaming capture at `width` x `height` in `fourcc`, with `count` mapped
buffers, already queued and streaming. A device that cannot stream capture is an error.

Effects: fail, io.

### `frame`

```gizlang
function frame(cam: Camera): bytes throws string
```

The next frame: waits for a filled buffer, copies its bytes out, and queues the buffer again.

Effects: fail, io.

### `close`

```gizlang
function close(cam: Camera): void
```

Stops streaming, unmaps the buffers and closes the device.

Effects: fail, io.

### `cameras`

```gizlang
function cameras(sys: System): Vec<Device.Device> throws IoError
```

The capture devices of the video class (`videoN` with a node).

Effects: fail, io.