← Index

x/sys/web

A window in a browser tab: (Web open title w h scale) listens for a page, and Sdl’s other messages draw to it, play sound on it, and read its keys and gamepads.

Class Web

A window in a browser tab: Sdl’s messages answered by a page that shows an RGBA picture on a canvas, plays signed 16-bit sound through Web Audio, and sends keys and gamepad input back over a WebSocket.

open listens on 127.0.0.1, ports 8080 to 8089 then any the kernel gives, unless listen! names others, and prints the page’s address on stderr.

%window-cell

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

%listen-cell

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

%stream-count

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

%guid

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

%page

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

(Web listen! host ports)

Name where the next open listens.

Parameters:

• host : STRING — Dotted-quad address to listen on: 127.0.0.1 for this machine only, 0.0.0.0 for every interface, as in a container
• ports : INTEGER|LIST — The port, or the candidates to try in order, as Socket tcp-listen-on takes them

Returns: STRING — The host

Examples:

(Web listen! "127.0.0.1" 8080) => "127.0.0.1"

(Web available?)

Whether a Web window can be opened: always, as it needs nothing outside x.

Returns: BOOL — #t

Examples:

(Web available?) => #t

(Web keys)

Keycodes by name for keys that are not printable characters: Sdl’s, as the page sends SDL’s keycodes.

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

Examples:

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

(Web key name)

The keycode the page sends for a named key.

Parameters:

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

Returns: INTEGER — SDL’s keycode

Examples:

(Web key (lit escape)) => 27

(Web buttons)

Gamepad button names, as Sdl’s: the page maps a standard gamepad’s buttons to them.

Returns: LIST — Button names

Examples:

(first (Web buttons)) => 'south

(Web axes)

Gamepad axis names, as Sdl’s.

Returns: LIST — Axis names

Examples:

(first (Web axes)) => 'left-x

(Web error)

The last error message: always empty, as Web raises its errors.

Returns: STRING — “”

Examples:

(Web error) => ""

(Web %ref win field)

A field of the window.

Parameters:

• win : VECTOR — A window from open
• field : SYMBOL — A field name

Returns: ANY — Its value

(Web %set! win field v)

Set a field of the window.

Parameters:

• win : VECTOR — A window from open
• field : SYMBOL — A field name
• v : ANY — The new value

Returns: ANY — v

(Web %field field)

The slot that holds a field of the window.

Parameters:

• field : SYMBOL — A field name

Returns: INTEGER — The slot

Examples:

(Web %field (lit page)) => 1

(Web %window)

The window open, or nil.

Returns: ANY — The window

(Web open title w h scale)

Listen for a browser and keep a w x h RGBA picture for it, scaled by whole multiples with nearest-pixel sampling. Prints the page’s address on stderr; frames drawn before a page connects are kept, and the last is sent when one does.

Parameters:

• title : STRING — The page’s title
• w : INTEGER — Picture width in pixels
• h : INTEGER — Picture height in pixels
• scale : INTEGER — Taken for Sdl’s sake: the page fits the picture to the tab

Returns: VECTOR — The window

(Web url win)

The address of the window’s page.

Parameters:

• win : VECTOR — A window from open

Returns: STRING — An http URL

(Web %serve! win)

Take any new connection and read whatever the page has sent, without waiting.

Parameters:

• win : VECTOR — A window from open

Returns: ANY — nil

(Web %connect! win fd)

Answer one HTTP request on fd: the page, the WebSocket the page opens, or not found.

Parameters:

• win : VECTOR — A window from open
• fd : INTEGER — A connection just accepted

Returns: ANY — nil

(Web %request fd)

An HTTP request’s head, read until its blank line or 16 KB.

Parameters:

• fd : INTEGER — A connection

Returns: STRING — The request head

(Web %respond fd status type body)

Send one HTTP response and its body.

Parameters:

• fd : INTEGER — A connection
• status : STRING — Status line’s code and words
• type : STRING — Content-Type
• body : STRING — The body, text

Returns: ANY — nil

(Web %header name request lower)

A request header’s value, or nil.

Parameters:

• name : STRING — A header name, lower case, with its colon
• request : STRING — The request head
• lower : STRING — The request head, lower case

Returns: ANY — The value, trimmed

(Web accept-key key)

The Sec-WebSocket-Accept answer to a WebSocket key (RFC 6455): the base64 of the SHA-1 of the key and the protocol’s GUID.

Parameters:

• key : STRING — A Sec-WebSocket-Key header’s value

Returns: STRING — The answer

Examples:

(Web accept-key "dGhlIHNhbXBsZSBub25jZQ==") => "s3pPLMBiTxaQ9kYGzzhZRbK+xOo="

(Web %upgrade! win fd request lower)

Make fd the page’s WebSocket, in place of any before it, and send it the window’s state.

Parameters:

• win : VECTOR — A window from open
• fd : INTEGER — A connection
• request : STRING — Its request head
• lower : STRING — The head, lower case

Returns: ANY — nil

(Web %drop! win)

Forget the page’s socket, closing it.

Parameters:

• win : VECTOR — A window from open

Returns: ANY — nil

(Web %send! win op head head-n body body-n)

Send one frame to the page, if there is one; a page that has gone is dropped.

Parameters:

• win : VECTOR — A window from open
• op : INTEGER — The opcode: 1 text, 2 binary, 8 close
• head : STRING — The payload’s first bytes
• head-n : INTEGER — How many
• body : ANY — The rest of the payload, or nil
• body-n : INTEGER — How many bytes of body

Returns: ANY — nil

(Web %put-be! p at v n)

Write v as n big-endian bytes.

Parameters:

• p : POINTER — Where
• at : INTEGER — Offset
• v : INTEGER — Value
• n : INTEGER — Bytes

Returns: ANY — nil

(Web %tell! win text)

Send the page a text message.

Parameters:

• win : VECTOR — A window from open
• text : STRING — A message: a word and its arguments

Returns: ANY — nil

(Web %read! win)

Read what the page has sent and queue its events; a page that has closed is dropped.

Parameters:

• win : VECTOR — A window from open

Returns: ANY — nil

(Web %frames! win bytes)

Take each whole frame from bytes, queue the events of its text, and keep the rest.

Parameters:

• win : VECTOR — A window from open
• bytes : LIST — Bytes read and not yet whole frames

Returns: ANY — nil

(Web %get-be bytes n)

The first n bytes read as a big-endian number.

Parameters:

• bytes : LIST — Bytes
• n : INTEGER — How many

Returns: INTEGER — The number

Examples:

(Web %get-be (list 1 44) 2) => 300

(Web %unmask bytes mask)

The payload with the mask taken off: each byte exclusive-or the mask’s byte at its place, four round.

Parameters:

• bytes : LIST — A payload
• mask : LIST — Four mask bytes, or nil

Returns: LIST — The bytes

Examples:

(Web %unmask (list 3 1) (list 1 2 3 4)) => (2 3)

(Web %event bytes)

The event a message names: its first word a symbol, each other word a number when it reads as one and a symbol when not.

Parameters:

• bytes : LIST — A text message’s bytes: an event’s words

Returns: LIST — The event

Examples:

(Web %event (list 112 97 100 45 117 112 32 115 111 117 116 104 32 48)) => ('pad-up 'south 0)

(Web %text bytes)

A string of the bytes.

Parameters:

• bytes : LIST — Byte values

Returns: STRING — The string

Examples:

(Web %text (list 104 105)) => "hi"

(Web %queue! win event)

Put an event at the end of the queue poll answers from.

Parameters:

• win : VECTOR — A window from open
• event : LIST — An event

Returns: ANY — nil

(Web scaling! win mode)

Set how the page scales the picture to the tab: by whole multiples, or as large as fits.

Parameters:

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

Returns: VECTOR — The window

(Web canvas win)

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

Parameters:

• win : VECTOR — A window from open

Returns: STRING — A region of wh4 bytes

(Web draw! win buf)

Keep the buffer as the frame; nothing is sent until present!.

Parameters:

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

Returns: VECTOR — The window

(Web present! win)

Send the frame drawn last to the page.

Parameters:

• win : VECTOR — A window from open

Returns: VECTOR — The window

(Web show! win buf)

Draw the buffer and send it.

Parameters:

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

Returns: VECTOR — The window

(Web read-pixels win)

The frame drawn last, as an RGBA buffer; nil before any.

Parameters:

• win : VECTOR — A window from open

Returns: ANY — A region of wh4 bytes, or nil

(Web fullscreen! win on)

Ask the page to fill the screen, or to leave it; a browser grants it only after a key or a click.

Parameters:

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

Returns: VECTOR — The window

(Web poll)

The next event from the page, or nil; the same events as Sdl’s poll answers.

Returns: ANY — An event list, or nil

(Web post-key! code)

Queue a key-down event, as a key pressed on the page would be.

Parameters:

• code : INTEGER — An SDL keycode

Returns: INTEGER — The code

(Web close win)

Tell the page the window is closed and close the sockets.

Parameters:

• win : VECTOR — A window from open

Returns: ANY — nil

(Web %now)

The wall clock in microseconds.

Returns: INTEGER — Microseconds since the epoch

(Web %opened s)

The message that opens a stream on the page.

Parameters:

• s : VECTOR — A stream

Returns: STRING — The message

(Web %rate s)

The stream’s bytes a second.

Parameters:

• s : VECTOR — A stream

Returns: INTEGER — Bytes a second

(Web audio-open rate chans)

Open a stream of signed 16-bit frames to the page; nothing is heard until a key or a click has started the page’s sound.

Parameters:

• rate : INTEGER — Frames a second, such as 44100
• chans : INTEGER — Channels: 1 or 2

Returns: VECTOR — The stream

(Web audio-put! s buf n)

Send n bytes of buf to play after what the stream has.

Parameters:

• s : VECTOR — A stream from audio-open
• buf : STRING — Samples, signed 16-bit little-endian, channels interleaved
• n : INTEGER — How many bytes of buf

Returns: VECTOR — The stream

(Web audio-queued s)

Bytes sent to the stream and not yet played, by the clock.

Parameters:

• s : VECTOR — A stream from audio-open

Returns: INTEGER — Bytes

(Web audio-clear! s)

Drop what the stream has not played.

Parameters:

• s : VECTOR — A stream from audio-open

Returns: VECTOR — The stream

(Web audio-close s)

Release the stream.

Parameters:

• s : VECTOR — A stream from audio-open

Returns: ANY — nil