# gizlang/gpu

a GPU context and the targets it draws into, over EGL and OpenGL ES 3 (gizlang/sys/gpu). A context has no window: it draws into a Target, an offscreen framebuffer of a color texture and a depth-stencil buffer. A program reads a target's pixels into a Bitmap (a page's WebGL canvas in a scene), or exports its texture as a dma-buf for a compositor to show without a copy. Calls between use() and the next context's use() go to this context; GL calls themselves are gizlang/sys/gpu's, as their C library gives them.

```gizlang
import * as Gpu from "gizlang/gpu";
```

## Types

### `Context`

```gizlang
type Context = { display: u64; context: u64; native: Native; }
```

A GPU context: its EGL display and context, and the authority its native memory comes from.

- `display`: `u64`
- `context`: `u64`
- `native`: `gizlang_native.Native`

### `Target`

```gizlang
type Target = { framebuffer: u64; texture: u64; depth: u64; width: i64; height: i64; }
```

An offscreen target: a framebuffer whose color is a texture (RGBA8) and whose depth and stencil are a renderbuffer.

- `framebuffer`: `u64`
- `texture`: `u64`
- `depth`: `u64`
- `width`: `i64`
- `height`: `i64`

### `Buffer`

```gizlang
type Buffer = { fd: i64; fourcc: u64; stride: i64; offset: i64; modifier: u64; }
```

A target's texture as a dma-buf (its file descriptor, DRM fourcc, stride, offset and format modifier).

- `fd`: `i64`
- `fourcc`: `u64`
- `stride`: `i64`
- `offset`: `i64`
- `modifier`: `u64`

## Functions

### `open`

```gizlang
function open(): Option<Context>
```

A GPU context of OpenGL ES 3 with no window, on the first GPU EGL finds; none where EGL or GLES is not installed or
no device takes ES 3 (Mesa's surfaceless platform, then the default display).

Effects: fail, io, alloc.

## Methods

### `Context.use`

```gizlang
function Context.use(self: Context): bool
```

Makes this the thread's current context: GL calls after it go here. False when EGL refuses.

Effects: fail, io, alloc.

### `Context.close`

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

Ends the context and what it holds.

Effects: fail, io, alloc.

### `Context.slot`

```gizlang
function Context.slot(self: Context): u64
```

A native word for one GL name a glGen call writes; Context.taken reads it and frees the word.

Effects: fail, io, alloc.

### `Context.taken`

```gizlang
function Context.taken(self: Context, at: u64): u64
```

The GL name at AT (Context.slot), whose word is freed.

Effects: fail, io, alloc.

### `Context.holding`

```gizlang
function Context.holding(self: Context, name: u64): u64
```

A native word holding the GL name NAME, for a glDelete call; the caller frees it.

Effects: fail, io, alloc.

### `Context.target`

```gizlang
function Context.target(self: Context, width: i64, height: i64): Option<Target>
```

A new target of WIDTH x HEIGHT pixels, bound as the framebuffer; none when the GPU cannot make it complete.

Effects: fail, io, alloc.

### `Context.release`

```gizlang
function Context.release(self: Context, target: Target): void
```

Frees TARGET's framebuffer, texture and depth buffer.

Effects: fail, io, alloc.

### `Context.pixels`

```gizlang
function Context.pixels(self: Context, target: Target, premultiplied: bool): Bitmap
```

TARGET's pixels, top row first, as straight alpha. PREMULTIPLIED says the drawing's colors are premultiplied by
their alpha (WebGL's default), which the bitmap undoes.

Effects: fail, io, alloc.

### `Context.exported`

```gizlang
function Context.exported(self: Context, target: Target): Option<Buffer>
```

TARGET's texture as a dma-buf for a compositor (EGL_MESA_image_dma_buf_export); none where the driver lacks it. The
caller closes the descriptor. Its rows go up from the bottom, as GL draws them.

Effects: fail, io, alloc.

## Constants

### `FRAMEBUFFER`

```gizlang
const FRAMEBUFFER = 0x8D40u
```

GL_FRAMEBUFFER: the target a framebuffer object is bound to.

### `RENDERBUFFER`

```gizlang
const RENDERBUFFER = 0x8D41u
```

GL_RENDERBUFFER: the target a renderbuffer is bound to.

### `TEXTURE_2D`

```gizlang
const TEXTURE_2D = 0x0DE1u
```

GL_TEXTURE_2D: the target of a two-dimensional texture.

### `RGBA`

```gizlang
const RGBA = 0x1908u
```

GL_RGBA: pixels of red, green, blue and alpha.

### `RGBA8`

```gizlang
const RGBA8 = 0x8058u
```

GL_RGBA8: the internal format of 8 bits a channel.

### `UNSIGNED_BYTE`

```gizlang
const UNSIGNED_BYTE = 0x1401u
```

GL_UNSIGNED_BYTE: one byte a channel in pixels read or written.

