Docs / standard library / Graphics (gg)

Graphics (gg)

The gg windowing, audio, and input layer: 21 intrinsics, headless by default.

pull "gg" opens the windowing, audio, and input layer (yes, gg, as in good game). It’s headless by default: present and audio no-op, input polls empty, nothing pops up on screen. Build with the desktop feature when you want a real window. The return shapes are identical either way, so all your game logic stays testable headless, no display required. All 21 intrinsics run on both the interpreter and the compiled paths.

Event kinds

Returned by gg.poll as (kind, code):

Kind	Value
`NONE`	0
`KEY_DOWN`	1
`KEY_UP`	2
`MOUSE_MOVE`	3
`QUIT`	4
`MOUSE_DOWN`	5
`MOUSE_UP`	6

For mouse buttons, code is 0 for left and 1 for right. QUIT fires only on a real window close. Esc is a normal KEY_DOWN / KEY_UP (code 27), so games can drive menus with it.

Keycodes

Letters A to Z and digits 0 to 9 are ASCII. Beyond those: SPACE = 32, ENTER = 10, ESC = 27, BACKSPACE = 8, TAB = 9; arrows UP = 256, DOWN = 257, LEFT = 258, RIGHT = 259.

Iruns in the interpreter (bet run)Cruns in the compiled backend

callsignaturedoes

video

gg.frame

(w, h, color) -> voidBegin a frame; clear the canvas to color (0x00RRGGBB).

gg.rect

(x, y, w, h, color) -> voidFill a rectangle (0xAARRGGBB).

gg.blit

(pixels: []u32, w, h) -> voidPresent a tightly-packed w*h framebuffer 1:1.

gg.show

(pixels: []u32, w, h) -> voidPresent a fixed-logical-size framebuffer, aspect-fit / letterboxed.

gg.size

() -> (w, h)Live window size.

gg.tex

(buf: []u8, byteOff, w, h) -> intUpload a w*h RGBA8 texture; returns a 1-based texture id.

gg.sprite

(tex, x, y) -> voidBlit a whole texture at (x, y).

gg.spriteSub

(tex, sx, sy, sw, sh, dx, dy) -> voidBlit a source sub-rectangle.

gg.flush

() -> voidPresent the composited canvas and pump input.

gg.title

(name: str) -> voidSet the window title.

audio

gg.audio

(samples: []i16, count) -> voidQueue count interleaved i16 samples (streaming ring).

gg.audioSpec

() -> (rate, channels)Device output spec.

gg.pending

() -> intInterleaved samples still queued (synth backpressure).

gg.sound

(buf: []i16, byteOff, byteLen, channels, rate) -> intRegister a PCM sound; returns a 1-based id.

gg.play

(soundId, loop, volume) -> intStart a voice; returns a 1-based voice id.

gg.stop

(voiceId) -> voidStop a voice.

gg.tune

(voiceId, volume, pan) -> voidLive-update a voice's volume + stereo pan.

input

gg.poll

() -> (kind, code)Next input event; kind == 0 (NONE) when the queue is empty.

gg.ticks

() -> intMonotonic nanosecond counter (hi-res timing).

gg.mouse

() -> (x, y)Mouse position in logical-canvas coords.

gg.mouseDelta

() -> (dx, dy)Signed raw mouse movement since the last call.

video

gg.frameIC

(w, h, color) -> void

Begin a frame; clear the canvas to color (0x00RRGGBB).

gg.rectIC

(x, y, w, h, color) -> void

Fill a rectangle (0xAARRGGBB).

gg.blitIC

(pixels: []u32, w, h) -> void

Present a tightly-packed w*h framebuffer 1:1.

gg.showIC

(pixels: []u32, w, h) -> void

Present a fixed-logical-size framebuffer, aspect-fit / letterboxed.

gg.sizeIC

() -> (w, h)

Live window size.

gg.texIC

(buf: []u8, byteOff, w, h) -> int

Upload a w*h RGBA8 texture; returns a 1-based texture id.

gg.spriteIC

(tex, x, y) -> void

Blit a whole texture at (x, y).

gg.spriteSubIC

(tex, sx, sy, sw, sh, dx, dy) -> void

Blit a source sub-rectangle.

gg.flushIC

() -> void

Present the composited canvas and pump input.

gg.titleIC

(name: str) -> void

Set the window title.

audio

gg.audioIC

(samples: []i16, count) -> void

Queue count interleaved i16 samples (streaming ring).

gg.audioSpecIC

() -> (rate, channels)

Device output spec.

gg.pendingIC

() -> int

Interleaved samples still queued (synth backpressure).

gg.soundIC

(buf: []i16, byteOff, byteLen, channels, rate) -> int

gg.playIC

(soundId, loop, volume) -> int

Start a voice; returns a 1-based voice id.

gg.stopIC

(voiceId) -> void

Stop a voice.

gg.tuneIC

(voiceId, volume, pan) -> void

Live-update a voice's volume + stereo pan.

input

gg.pollIC

() -> (kind, code)

Next input event; kind == 0 (NONE) when the queue is empty.

gg.ticksIC

() -> int

Monotonic nanosecond counter (hi-res timing).

gg.mouseIC

() -> (x, y)

Mouse position in logical-canvas coords.

gg.mouseDeltaIC

() -> (dx, dy)

Signed raw mouse movement since the last call.

← Standard library