← Index

x/sys/sdl

A window that shows an RGBA pixel buffer, with keyboard and window events and streams of sound, through the host’s SDL3 over the dlopen FFI.

Class Sdl

A window that shows an RGBA pixel buffer, its keyboard and window events, and streams of sound, through the host’s SDL3 loaded with dlopen.

SDL3 is looked for at the path given to load!, then as libSDL3.so.0, libSDL3.0.dylib, and under /opt/homebrew/lib and /usr/local/lib. A missing library raises a label ‘io.

%path-cell

Static field: data held by Sdl itself, not by its instances.

%init-video

Static field: data held by Sdl itself, not by its instances.

%init-gamepad

Static field: data held by Sdl itself, not by its instances.

%init-audio

Static field: data held by Sdl itself, not by its instances.

%s16

Static field: data held by Sdl itself, not by its instances.

%default-playback

Static field: data held by Sdl itself, not by its instances.

%buttons

Static field: data held by Sdl itself, not by its instances.

%axes

Static field: data held by Sdl itself, not by its instances.

%mouse-buttons

Static field: data held by Sdl itself, not by its instances.

%rgba32

Static field: data held by Sdl itself, not by its instances.

%streaming

Static field: data held by Sdl itself, not by its instances.

%integer-scale

Static field: data held by Sdl itself, not by its instances.

%letterbox

Static field: data held by Sdl itself, not by its instances.

%nearest

Static field: data held by Sdl itself, not by its instances.

%resizable

Static field: data held by Sdl itself, not by its instances.

%event-size

Static field: data held by Sdl itself, not by its instances.

%keys

Static field: data held by Sdl itself, not by its instances.

(Sdl keys)

Keycodes by name for keys that are not printable characters.

Returns: LIST — ((name . keycode) …)

Examples:

(first (Sdl keys)) => ('up . 1073741906)

(Sdl %handle)

The libSDL3 handle, or nil when no candidate opens.

Returns: POINTER|NIL — The dlopen handle

(Sdl %sym name)

The named SDL3 function; raises a label ‘io when libSDL3 is not found.

Parameters:

• name : STRING — SDL function name

Returns: POINTER — The function pointer

(Sdl %ok r what)

Raise a label ‘io with SDL’s error when a bool result is false.

Parameters:

• r : INTEGER — A C bool result
• what : STRING — The call, for the message

Returns: ANY — nil

(Sdl %made p what)

The pointer, or a label ‘io with SDL’s error when it is NULL.

Parameters:

• p : INTEGER — A pointer result
• what : STRING — The call, for the message

Returns: INTEGER — The pointer, as an integer

(Sdl %zeroed n)

A (str make) region of n zero bytes.

Parameters:

• n : INTEGER — Byte count, a multiple of 8

Returns: STRING — The region

(Sdl load! path)

Name the libSDL3 to load ahead of the default names, as a game shipping its own copy does.

Parameters:

• path : STRING — A libSDL3 file to try first

Returns: STRING — The path

Examples:

(Sdl load! "/nonexistent/libSDL3.dylib") => "/nonexistent/libSDL3.dylib"

(Sdl available?)

Whether a libSDL3 can be opened.

Returns: BOOL — #t when one opens

(Sdl error)

SDL’s last error message.

Returns: STRING — The message, empty when there is none

(Sdl hint! name value)

Set an SDL hint; video and render driver hints take effect at the next open.

Parameters:

• name : STRING — An SDL hint name, such as SDL_VIDEO_DRIVER
• value : STRING — Its value

Returns: BOOL — #t when SDL took the hint

(Sdl open title w h scale)

Start SDL’s video and open a resizable window that shows a w x h RGBA picture, scaled by whole multiples with nearest-pixel sampling.

Parameters:

• title : STRING — Window title
• w : INTEGER — Picture width in pixels
• h : INTEGER — Picture height in pixels
• scale : INTEGER — Initial window size, in multiples of the picture

Returns: LIST — The window: (window renderer texture w h)

(Sdl scaling! win mode)

Set how the picture fills the window as it is resized: by whole multiples, every pixel the same size and bars round the rest, or as large as fits, the bars only on two sides and the pixels a little uneven.

Parameters:

• win : LIST — A window from open
• mode : SYMBOL — whole: whole multiples only; fit: as large as the window allows, its shape kept

Returns: LIST — The window

(Sdl canvas win)

A zeroed RGBA buffer the size of the window’s picture: transparent black.

Parameters:

• win : LIST — A window from open

Returns: STRING — A region of wh4 bytes

(Sdl draw! win buf)

Upload the buffer and draw it over the whole picture; nothing shows until present!.

Parameters:

• win : LIST — A window from open
• buf : STRING — An RGBA buffer the window’s size

Returns: LIST — The window

(Sdl present! win)

Put the drawn frame on screen.

Parameters:

• win : LIST — A window from open

Returns: LIST — The window

(Sdl show! win buf)

Draw the buffer and present it.

Parameters:

• win : LIST — A window from open
• buf : STRING — An RGBA buffer the window’s size

Returns: LIST — The window

(Sdl read-pixels win)

The frame drawn since the last present, read back as an RGBA buffer; call it before present!.

Parameters:

• win : LIST — A window from open

Returns: STRING — A region of wh4 bytes

(Sdl poll . win)

The next queued event, or nil when the queue is empty.

A gamepad is opened when its pad-added arrives and closed at pad-removed; pads already connected at open arrive as pad-added too.

The mouse’s X Y are in the window’s pixels, or in the picture’s when the window is given, whole and toward zero; a place in the bars beside the picture lies outside it, below 0 or past its size.

Parameters:

• win : LIST — A window from open: the mouse’s places in its picture’s pixels

Returns: LIST|NIL — (key-down KEY MOD REPEAT), (key-up KEY MOD REPEAT), (mouse-down BUTTON X Y), (mouse-up BUTTON X Y), (mouse-motion X Y HELD), (pad-down BUTTON PAD), (pad-up BUTTON PAD), (pad-axis AXIS VALUE PAD), (pad-added PAD), (pad-removed PAD), (quit), (close) or (other TYPE)

(Sdl %name names i)

The symbol for an SDL enum value, or the value itself past the named ones.

Parameters:

• names : LIST — Symbols in SDL’s enum order
• i : INTEGER — An enum value

Returns: SYMBOL|INTEGER — The name, or i

Examples:

(Sdl %name (Sdl %buttons) 11) => 'dpad-up

(Sdl %sint16 u)

The field as a signed 16-bit value.

Parameters:

• u : INTEGER — A 16-bit field read unsigned

Returns: INTEGER — -32768 to 32767

Examples:

(Sdl %sint16 65535) => -1

(Sdl %f32-int b)

The float as a whole number, toward zero; SDL gives the mouse’s places as floats.

Parameters:

• b : INTEGER — A 32-bit IEEE float’s bits, read as an integer

Returns: INTEGER — The whole part

Examples:

(Sdl %f32-int 0x41200000) => 10
(Sdl %f32-int 0xBF800000) => -1

(Sdl %held state)

The mouse buttons held, by name, for the flags SDL gives with a motion.

Parameters:

• state : INTEGER — SDL’s mouse button flags

Returns: LIST — Names from (Sdl mouse-buttons)

Examples:

(Sdl %held 5) => ('left 'right)

(Sdl mouse-buttons)

Mouse button names in SDL’s order, button 1 first.

Returns: LIST — (left middle right x1 x2)

Examples:

(List ref 2 (Sdl mouse-buttons)) => 'right

(Sdl buttons)

Gamepad button names in SDL’s order; south is the bottom face button, Xbox A.

Returns: LIST — (south east west north …)

Examples:

(List ref 0 (Sdl buttons)) => 'south

(Sdl axes)

Gamepad axis names in SDL’s order; sticks run -32768 to 32767, triggers 0 to 32767.

Returns: LIST — (left-x left-y right-x right-y left-trigger right-trigger)

Examples:

(List ref 4 (Sdl axes)) => 'left-trigger

(Sdl fullscreen! win on)

Switch the window to the desktop’s fullscreen or back; the picture keeps its whole-multiple scaling.

Parameters:

• win : LIST — A window from open
• on : BOOL — #t for fullscreen, #f for a window

Returns: LIST — The window

(Sdl raise! win)

Bring the window to the front and give it the keyboard, as far as the system allows: it may refuse to take the keyboard from another program.

Parameters:

• win : LIST — A window from open

Returns: LIST — The window

(Sdl post-key! code)

Queue a key-down event for code, as if it had been pressed: input for tests and replays.

Parameters:

• code : INTEGER — An SDL keycode

Returns: BOOL — #t when SDL queued it

(Sdl key name)

The keycode of a named key that is not a printable character.

Parameters:

• name : SYMBOL — A key name from (Sdl keys)

Returns: INTEGER|NIL — The keycode, or nil for an unknown name

Examples:

(Sdl key (lit escape)) => 27

(Sdl audio-open rate chans)

Start SDL’s audio and open a stream to the default playback device that plays signed 16-bit little-endian frames, already running: what is put on it plays as soon as the device takes it. Each stream is mixed with every other one open.

With the hint SDL_AUDIO_DRIVER set to dummy, a stream opens and drains with no sound device, as a spec needs.

Parameters:

• rate : INTEGER — Frames a second, such as 44100
• chans : INTEGER — Channels a frame: 1 mono, 2 stereo, left first

Returns: INTEGER — The stream, an SDL_AudioStream pointer as an integer

(Sdl audio-put! s buf n)

Queue the first n bytes of buf to play after what is already queued. SDL copies them: buf may be written again at once.

Parameters:

• s : INTEGER — A stream from audio-open
• buf : STRING — A region of frames
• n : INTEGER — Bytes of it to queue, from its start

Returns: INTEGER — n

(Sdl audio-queued s)

Bytes queued on the stream and not yet taken by the device: how far ahead of the speaker the stream is.

Parameters:

• s : INTEGER — A stream from audio-open

Returns: INTEGER — A byte count, 0 when it has run dry

(Sdl audio-clear! s)

Drop everything queued on the stream, unplayed: the next put plays at once.

Parameters:

• s : INTEGER — A stream from audio-open

Returns: INTEGER — The stream

(Sdl audio-close s)

Stop the stream and release it and its device; what was queued is dropped.

Parameters:

• s : INTEGER — A stream from audio-open

Returns: ANY — nil

(Sdl close win)

Release the window’s texture, renderer and window, and shut SDL down.

Parameters:

• win : LIST — A window from open

Returns: ANY — nil