GizStack
View .mdOpen in ChatGPTOpen in Claude

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.