SDL2 for the POSIX build

Windows, drawing, keyboard, mouse, images, text and sound for games, through the shared libraries of SDL2. Nothing is linked into lugforth: the libraries are opened at run time (dlopen) the first time you use them.

sdl2                          \ load, sdl2 becomes your vocabulary
3 to zoom  320 240 screen     \ 320x240 logical pixels, shown 3 times bigger
: frame  events  black color cls  red color 10 10 50 50 box  flip ;
: run  begin frame quit? until close-screen ;
run

Examples: sdl2_demo.fs (tour of the words), sdl2_breakout.fs (a game, about 200 lines), sdl2_drums.fs (16-step drum machine), fm/sdl2_fm.fs (two operator FM synthesizer, MIDI in, kept out of the interpreter: see fm/README.md), sdl2_pianoroll.fs (piano roll with soundfont playback and export to .mid and ABC, POSIX only), sdl2_roguelike.fs (tile sheet, with music), sdl2_3d.fs (turning wireframe cube, pyramid and octahedron), sdl2_2048.fs (2048 with a slide and pop animation, --no-anim turns it off; digits drawn from a 3x5 bitmap), pinball/pinball.fs (a pinball in the style of Night Mission, fixed point physics). Breakout, drums, the FM synthesizer and roguelike also run in the browser.

All words: SDL2-words.md. The short words also exist in the web build, see SDL2-web.md.

Packages

Typing a loader again puts sdl2 back on top. All words below live in the sdl2 vocabulary, with the raw C names (SDL_Init, ...) for anything without a short word. sdl2 is also where your definitions go.

Short words (sdl2)

Screen: screen ( w h -- ), close-screen, zoom (value, set before screen), title ( a n -- ), fullscreen ( f -- ), cursor ( f -- ), width, height.

Colors: color ( $rrggbb -- ), rgb ( r g b -- ), rgba ( r g b a -- ), alpha ( a -- ), and named colors black white red green blue yellow cyan magenta orange purple pink brown gray (red color), and ink ( n -- ), a color by number from 0 to 15 (0 black, 1 red, 2 green, 3 yellow, 4 blue, 5 magenta, 6 cyan, 7 white...).

Drawing: cls, dot ( x y -- ), line ( x1 y1 x2 y2 -- ), box ( x y w h -- ), frame ( x y w h -- ), hline ( x y w -- ), disc ( cx cy r -- ), circle ( cx cy r -- ), flip, pixel@ ( x y -- $rrggbb ).

Frame loop: events (call once per frame), quit?, quit!, wait, ticks ( -- ms ), delay ( ms -- ), dt (ms taken by the last frame).

Input: pressed? ( key -- f ) with [char] a, key-left key-right key-up key-down key-space key-enter key-esc key-tab key-backspace, LEFT-BUTTON MIDDLE-BUTTON RIGHT-BUTTON, mouse-x, mouse-y, last-key, wheel. Same names and meaning as the generic graphics interface. scan? ( scancode -- f ) tells whether a key is held by its place on the keyboard (SDL scancode: 4 is the key A of a QWERTY, 20 is Q...), whatever the layout: use it for a piano or WASD style row of keys that must not move on an AZERTY keyboard.

Beeps (no library beyond libSDL2): beep ( freq ms -- ) queues a tone, so several beep in a row play as a melody. wave sets the shape (0 square, 1 triangle, 2 saw, 3 noise, 4 sine), as color sets the color: 1 wave, or the words square triangle saw noise sine. beep-volume ( n -- ) and pitch-drop ( n -- ) work the same way; read a setting back with wave@, beep-volume@, pitch-drop@. to wave still works. Also silence, beeping?.

play ( a n -- ) queues notes written in MML (Music Macro Language, the PLAY of the BASICs of MSX, GW-BASIC and QBasic): s" t140 o4 l8 c d e c e4 g4 r4 >c2" play.

Spaces are free; the settings stay from one play to the next. Differences from the dialects: the octave numbering is the MSX one (o4 c is the middle C; check a tune written for another dialect, they differ); no chords, no m modes (legato, staccato) and no x (play a string variable). It works at the prompt after sdl2 (the console window, the boards, the web page).

Several voices: a comma in the string starts another voice, and the voices start together (s" o4 e d c d e e e2, o3 c1 g1" play). 4 voices at most, 512 notes each; each voice begins with the octave, length, tempo, wave and volume the play started with. On Linux the voices are mixed into one buffer and queued whole (so a very long tune takes a moment to prepare); on the boards each voice has its own queue; on the web page the notes of every voice are scheduled from the same moment.

Envelope: adsr ( attack decay sustain release -- ) (ms, ms, percent, ms) shapes every beep and every note of play; the release is the end of the note, not added to it. adsr@ reads the values, adsr-off removes the envelope (the default). Hits and ABC tunes are not affected.

Hits: drum-hit ( freq ms -- ) starts at once and plays over other sounds (8 at a time), fading out; pitch-drop (percent) makes the pitch fall, enough for a kick drum. Call flip or delay regularly, as a game loop does. Use beep or drum-hit in a program, not both.

Images (sdl2-image)

load-image ( a n -- img ), free-image, image-size ( img -- w h ), draw ( img x y -- ), draw-size ( img x y w h -- ), draw-part ( img sx sy sw sh x y w h -- ) for sprite sheets, image-alpha, image-tint. Load images after screen. A name with directories that is not found is tried again without them, so s" examples/tiles.png" load-image also works from inside examples/.

Text (sdl2-ttf)

load-font ( a n pt -- font ), font ( font -- ), free-font, text ( x y a n -- ) in the current color, text-size ( a n -- w h ).

Sound (sdl2-mixer)

load-sound ( a n -- snd ), play ( snd -- ), free-sound, sound-volume, stop-sounds, sounds-playing, load-music ( a n -- mus ), music ( mus -- ) (loops), music-once, stop-music, music-volume, music?, free-music. Overlapping sounds are mixed.

Music files: OGG, MP3, FLAC, Opus, WAV, MOD and MIDI, as far as your SDL2_mixer has the decoders. MIDI needs a soundfont: soundfont ( a n -- ) sets a .sf2 or .sf3 (soundfont? returns a flag instead of throwing). The name is tried as given, then in the current directory, then in the script's directory, so s" mygame.sf2" soundfont finds a file beside the program. Without one, FluidSynth uses the system soundfont if there is one.

Tunes (sdl2-abc)

Tunes written in ABC notation, a text format for melodies, can be played with the soundfont. Type sdl2-abc once (it loads sdl2-mixer if needed). Since ABC uses the bar character, write the tune with r~ ... ~, a multi-line string that ends at a tilde:

sdl2-abc
s" gm.sf2" soundfont?  drop        \ optional, a soundfont beside the program
: tune r~ X:1
T:Scale
M:4/4
L:1/4
Q:1/4=120
K:C
%%MIDI program 0
C D E F | [CEG]2 z2 |
~ ;
tune abc-play                      \ once; abc-loop repeats; tune-stop stops

abc ( a n -- ) reads the tune; tune-play, tune-loop, tune-stop and tune-playing? play it; abc-play and abc-loop do both. After abc you can change tune-bpm and tune-program (General MIDI instrument), read tune-ms and tune-notes, or write a MIDI file with tune-save.

Understood: K: L: M: Q: and %%MIDI program n; notes, accidentals, octave marks, lengths, rests, chords, ties, broken rhythm, tuplets, bar lines. Skipped: chord symbols, decorations, grace notes, comments, lyrics. Not supported: repeats, several voices, tempo changes. At most 1024 notes. The web build has the same words with a simple synthesizer.

Console window (sdl2_console.fs)

In the console window, graphic makes the drawing words work at the prompt (0 0 100 100 line): a 640x480 texture receives them, drawn under the text, centered, in proportion; cls clears it, flip redraws the window. w h graphic-size sets the size of the texture (16 to 4096), kept in proportion in the window. A program that calls screen ends it. The pen is saved and restored around each redraw.

lugforth --gui [file.fs] opens a console window (type and key go to an SDL window). The code is part of the binary: gui-load loads it, then desktop console starts it (Android uses gui-load smooth-font console). Without SDL2 or a display, --gui says so and keeps the terminal.

The menu is hidden: the button at the top right, or F10, shows it (a right click on the open menu closes it; a right click on the button hides the button, and on its place shows it again) (Examples, only when the folder holds .fs files, View, Colors, Font, Help). Examples lists the .fs files of LUGFORTH_EXAMPLES (default: the current directory). Colors has a color picker for the text and for the background (a square of saturation and brightness, a strip of hues, the hex value) and a few themes. Alt+Enter, or View, toggles full screen. Font lists the fixed width TrueType and OpenType fonts found in /usr/share/fonts, ~/.local/share/fonts and ~/.fonts (the wheel scrolls a long menu). View also has More margin and Less margin (margin= in the .ini, in pixels). Also: mouse selection (copied), middle click or Ctrl+V to paste, wheel or PageUp/PageDown to scroll back, Ctrl+wheel, Ctrl +/-, Ctrl 0 for the text size. ASCII only.

Settings are kept in lugforth.ini in ~/.local/share/lugforth (or LUGFORTH_HOME):

size=15
fg=D2D2D2
bg=000000
font=/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf
margin=12
fullscreen=Alt+Enter

fullscreen= is the key of full screen: Alt+Enter, F11, Ctrl+Shift+F...

font= wins over LUGFORTH_FONT, then DejaVu Sans Mono and other common fonts of the system. ports/posix/sdl2_console_tests.fs tests the settings (dummy drivers, like the other SDL tests).

Limits

• Calls pass integers and pointers only: no floats or structs by value (SDL_RenderCopyEx, rotation...).
• No callbacks from C into Forth: audio uses queues (beep, drum-hit) or the mixer.
• Mouse positions are in logical pixels, whatever the zoom.
• pressed? reads the held state once per events; a press shorter than one frame is missed.
• Names ignore case, so the function SDL_Quit is bound as sdl-shutdown; SDL_QUIT is the event constant.

Tests

They need the libraries, so ninja posix does not run them:

SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy out/posix/lugforth ports/posix/sdl2_tests.fs

Same for sdl2_media_tests.fs and sdl2_abc_tests.fs.

SDL2 word reference

Every word of the sdl2 vocabulary, for the POSIX build (out/posix/lugforth). For a tour with examples read SDL2.md first. This page is the complete list.

The words come from five loaders, each loading its source the first time it is typed. They all add to the same sdl2 vocabulary:

Stack notation: x y are pixel coordinates, w h sizes, a n a Forth string (address, length), z a zero terminated C string, f a flag, $rrggbb a color. img snd mus font are handles returned by the load- words. Values are read by name and changed with to: 3 to zoom.

Raw C bindings keep the C name and argument order. Each one pushes exactly one result. When the table says void the C function returns nothing but a value is still pushed: drop it. Int results that can be negative (-1 for an error) should go through sign-extend from the posix vocabulary.

Word lists: alphabetical index.

Core (sdl2)

Screen

Colors

Drawing

Timing

Input

Beeps and hits

Constants (core)

Raw C bindings (core)

sdl-shutdown is the C function SDL_Quit: lugforth ignores case, so it could not share its name with the SDL_QUIT event constant.

Internal words (core)

Used by the words above. Listed because they are in the vocabulary and can hide or be hidden by your own names.

Images (sdl2-image)

Type sdl2-image once, then load images after screen.

Raw C bindings (image)

Internal words (image)

Text (sdl2-ttf)

Type sdl2-ttf once. Text is drawn in the current color.

Raw C bindings (text)

The SDL_Color argument of TTF_RenderUTF8_Blended is passed packed, as pen.

Internal words (text)

Sound (sdl2-mixer)

Type sdl2-mixer once. Not to be confused with beep, which is in the core.

Constants (sound)

Raw C bindings (sound)

Internal words (sound)

Tunes (sdl2-abc)

Type sdl2-abc once (it loads sdl2-mixer if needed). A tune written in ABC notation (see abcnotation.com) is read, turned into a MIDI file in a temporary file (deleted once loaded) and played by SDL2_mixer through FluidSynth, with the soundfont given by soundfont or the one of the system. The same words exist in the web build, where simple oscillators play the notes.

Internal words (tunes)

The reader itself lives in the vocabulary abc-int, which is not searched by default.

Drawing at the prompt, and the boards (rpi, efi, web)

graphic makes the drawing words work at the prompt of the bare-metal console (Raspberry Pi, PC UEFI), of the console window (--gui) and of the web terminal, without screen: a drawing area is shown under (web: above) the text, which stays usable. 0 0 100 100 line, red color, cls. The words below exist in the short words of those builds; they are listed here with the others.

Drawing area

Keys on the boards (internal)

The serial line of the boards is read as a stream of characters, without key releases (a USB keyboard is read by C code, see pressed?): a key counts as held for key-hold milliseconds after its last press.

Sound on the PC (efi)

Aliases

Other names for the same word, as other Forths and BASICs call them. An alias is a plain colon definition that calls the word, so it works the same everywhere sdl2 does (Linux, web, rpi, efi). Add new ones here.

Where to change them: an alias is one line, : plot ( x y -- ) dot ;, written right after the word it renames in each of the three sources of the short words, which must stay equal:

Then add the row to the table above, and the word to the alphabetical index at the end of this page.

Where the other sections of this page come from: this file is written by hand, section by section, after the sources: Core, Images, Text, Sound and Tunes (ports/posix/sdl2.fs, sdl2_image.fs, sdl2_ttf.fs, sdl2_mixer.fs, sdl2_abc.fs); the words of the boards and the web page (ports/baremetal/sdl2.fs, ports/web/sdl2.fs, ports/web/sdl2_abc.fs); sound-off and snd-ok (ports/efi/sound_ini.fs, ports/efi/hda.h). The generated list of the other words is docs/WORDS.md (see docs/dev/PITFALLS.md, "Adding words").

Alphabetical index

abc abc-loop abc-play active-hook alpha arrow audio-open audio-open? beep beep-volume beeping? black blue box brown c-close c-mkstemps circle close-screen cls color cursor cyan delay disc dot draw draw-part draw-size drum-hit dt escape events flip font forget-keys frame free-font free-image free-music free-sound fullscreen gfx-cls gfx-mode gfx-on graphic graphic-on graphic-size gray green height hline image-alpha image-size image-tint IMG_LoadTexture ink key-backspace key-down key-enter key-esc key-hit key-hold key-left key-right key-space key-tab key-times key-up key-within last-key latency LEFT-BUTTON line load-font load-image load-music load-sound magenta MIDDLE-BUTTON Mix_CloseAudio Mix_FreeChunk Mix_FreeMusic Mix_HaltChannel Mix_HaltMusic Mix_LoadMUS Mix_LoadWAV_RW Mix_OpenAudio Mix_PlayChannelTimed Mix_Playing Mix_PlayingMusic Mix_PlayMusic Mix_SetSoundFonts Mix_Volume Mix_VolumeMusic mouse-x mouse-y music music-once music-volume music? noise one-key orange pen pen-a pen-b pen-g pen-r pink pitch-drop pixel@ play plot pressed? purple quit! quit? red render-hook renderer rgb rgba RIGHT-BUTTON sample-rate saw scan? screen screen-open? sdl sdl-error sdl-shutdown SDL_ClearQueuedAudio SDL_CloseAudioDevice SDL_CreateRenderer SDL_CreateTexture SDL_CreateTextureFromSurface SDL_CreateWindow SDL_Delay SDL_DestroyRenderer SDL_DestroyTexture SDL_DestroyWindow SDL_FreeSurface SDL_GetError SDL_GetKeyboardState SDL_GetMouseState SDL_GetQueuedAudioSize SDL_GetTicks SDL_Init SDL_InitSubSystem SDL_OpenAudioDevice SDL_PauseAudioDevice SDL_PollEvent SDL_PushEvent SDL_QueryTexture SDL_QueueAudio SDL_RenderClear SDL_RenderCopy SDL_RenderDrawLine SDL_RenderDrawPoint SDL_RenderDrawRect SDL_RenderFillRect SDL_RenderPresent SDL_RenderReadPixels SDL_RenderSetLogicalSize SDL_RWFromFile SDL_SetHint SDL_SetRenderDrawBlendMode SDL_SetRenderDrawColor SDL_SetTextureAlphaMod SDL_SetTextureBlendMode SDL_SetTextureColorMod SDL_SetWindowFullscreen SDL_SetWindowTitle SDL_ShowCursor SDL_UpdateTexture SDL_WaitEvent sdlimg sdlmix sdlttf setting silence sine snd-ok sound sound-off sound-on sound-volume soundfont soundfont? sounds-playing square stop-music stop-sounds text text-size ticks ticks>ms title triangle TTF_CloseFont TTF_Init TTF_OpenFont TTF_Quit TTF_RenderUTF8_Blended TTF_SizeUTF8 tune-bpm tune-level tune-loop tune-midi tune-ms tune-notes tune-play tune-playing? tune-program tune-save tune-send tune-stop wait wave wheel white width window-handle yellow zoom

sdl2 short words for the Web

The web build has the same sdl2 short words as the Linux build (SDL2.md), drawn on an HTML canvas. A game written with them runs unchanged in both: examples/games/sdl2_breakout.fs is loaded as is by ports/web/sdl2_breakout.html, examples/music/sdl2_drums.fs by ports/web/sdl2_drums.html, examples/music/fm/sdl2_fm.fs (an FM synthesizer with MIDI input, see examples/music/fm/README.md) by examples/music/fm/sdl2_fm.html, examples/games/sdl2_roguelike.fs (with its tile sheet examples/games/sdl2_tiles.png) by ports/web/sdl2_roguelike.html and examples/games/pinball/ by ports/web/sdl2_pinball.html, and examples/games/sdl2_raycaster.fs (a 3D maze, steered with the mouse) by ports/web/sdl2_raycaster.html. The cells of the web build are 32 bits: a game that works in 16.16 fixed point must multiply through */ (see the raycaster).

At the prompt of terminal.html, as in the console window on Linux, graphic opens a drawing area above the text (640x480, scaled to half the height of the page at most; w h graphic-size for another size) and the drawing words work from the prompt, the terminal staying usable, also on a phone: graphic, then 10 10 150 140 line, red color 200 20 100 60 box, cls. sdl2 alone also gives the sound words at the prompt (s" t200 o4 c d e" play, 440 300 beep): the first key press or tap lets the page play sounds.

sdl2                          \ loads on first use, like on Linux
3 to zoom  320 240 screen     \ opens a canvas over the page
: frame  events  black color cls  red color 10 10 50 50 box  flip ;
: run  begin frame quit? until close-screen ;
run

Try the games

The page loads its Forth file with an XMLHttpRequest, which browsers refuse on file://, so serve the build directory over http:

ninja web
cd out/web && python3 -m http.server
# then open http://localhost:8000/sdl2_breakout.html
# or            http://localhost:8000/sdl2_drums.html
# or            http://localhost:8000/sdl2_fm.html
# or            http://localhost:8000/sdl2_roguelike.html
# or            http://localhost:8000/sdl2_pinball.html

Arrows, mouse or touch move the paddle. Space, click or tap launches the ball. Esc quits, and the page then offers "Play again".

In the drum machine everything can be done with the mouse: click or drag on the grid, buttons for play/stop, tempo - and + (1 bpm with the left button, 5 with the right one, hold to repeat), CLR and X (quit), and the colored pads on the left play the drums. The keyboard works too: space, up/down (5 bpm), 1 2 3 4, c, Esc.

In the roguelike, arrows or w a s d move, space waits and a click steps toward the clicked tile.

In the pinball (Night Raid), z and m or the arrows move the flippers, down held then let go launches the ball, space or n nudges and Enter starts a game. On a touch screen (or with ?touch in the address) the page shows buttons over the game: the two flippers at the bottom, LAUNCH, START and NUDGE. Each one follows its own finger and sets the key in context.sdl.down (the same codes as the keyboard), so both flippers can be held at once, which the single pointer of the canvas cannot do.

What exists

These words have the same names and stack effects as on Linux, see SDL2-words.md for what each one does:

• Screen: screen close-screen screen-open? zoom width height title fullscreen cursor
• Colors: color rgb rgba alpha and the named colors black white red green blue yellow cyan magenta orange purple pink brown gray
• Drawing: cls dot line box frame hline disc circle flip pixel@
• Timing: ticks delay dt
• Input: events quit? quit! pressed? scan? last-key mouse-x mouse-y wheel, the key- constants (key-left key-right key-up key-down key-space key-enter key-esc key-tab key-backspace) and LEFT-BUTTON MIDDLE-BUTTON RIGHT-BUTTON
• Images (the words of sdl2-image, which is a no-op here): load-image free-image image-size draw draw-size draw-part image-alpha image-tint
• Beeps and hits: beep drum-hit pitch-drop silence beeping? wave beep-volume audio-open audio-open? latency

What is different

• Not available: the raw SDL_ words, sdl2-ttf, the sound and music files of sdl2-mixer (load-sound, play, load-music, music...), and a few helpers: wait sdl-error window-handle renderer pen pen-r pen-g pen-b pen-a sample-rate.
• screen puts a black layer with its own canvas over the whole page, so the terminal is hidden while the game runs. The canvas keeps its aspect ratio, shown at zoom times its size or smaller if the window is too small. close-screen removes it.
• flip waits for the next animation frame, so games run at the screen refresh rate, and stop while the tab is hidden.
• Keys are taken from the terminal while a screen is open: they do not end up typed in it. Combinations with Ctrl, Alt or Meta and the F keys are not intercepted (Ctrl combinations are still handled by the terminal, as in any page of the web build).
• pressed? also sees a key or button pressed and released between two events, which the Linux version misses.
• Mouse and touch positions are in logical pixels, as on Linux, and a touch counts as LEFT-BUTTON.
• On a phone, the keyboard of the device does not come up while a screen is open: the terminal gives the focus to its hidden text field on a tap only when no screen is open, and screen takes the focus away from it.
• Images are loaded by the browser, so any format it reads works. load-image waits for the file (the interpreter yields meanwhile) and throws if it cannot be loaded. As on Linux, a name with directories that is not found is tried again without them: s" examples/games/sdl2_tiles.png" finds sdl2_tiles.png next to the page. image-tint multiplies the colors, as in SDL, using a copy of the image kept for each color.
• Sound starts after the first key press or click, because browsers refuse to play sound before. Beeps before that are dropped, and a queue more than two seconds long is not extended. A drum-hit plays at once over the other sounds, with at most 24 sounds alive.
• Tunes (sdl2-abc, the reader of ABC notation, see SDL2.md) have the same words as on Linux: abc abc-play abc-loop tune-play tune-loop tune-stop tune-playing? tune-bpm tune-program tune-ms tune-notes, but there is no MIDI synthesizer or soundfont in a browser. Each note is played by an oscillator (the triangle wave, or the one chosen with wave), so the instrument of %%MIDI program is ignored, and tune-midi and tune-save do not exist. soundfont? always answers false and soundfont does nothing, so a program that names a soundfont runs unchanged; sdl2-mixer only exists to be typed and gives music-volume. A looping tune waits for the sound to be allowed and starts at its next repeat if it was not yet. Loudness is music-volume (0 to 128, as on Linux).
• scan? takes the place of a key (KeyboardEvent.code), so a row of piano keys does not move on an AZERTY keyboard. Only letters, digits, comma, period, slash, semicolon, quote, brackets, minus, equal, space, enter, escape, tab, backspace and the arrows have a scancode here.
• line uses Bresenham's algorithm and may differ by a pixel from the SDL one.
• bye stops the web interpreter. A game file that ends with bye, like the breakout, leaves the page inert after run returns (the browser console shows an objects[op] is not a function error, which a plain bye in the terminal page gives as well). Reload the page to start again.

Tests

Checked with Chrome 150 without a screen, driven through the DevTools protocol: the page loads without console errors, the breakout is drawn, moving the pointer and holding a key move the paddle, a very short tap on space launches the ball, a bot following the ball with the mouse breaks bricks and schedules sound, Esc closes the screen. The drum machine page was checked the same way: a click on the grid switches a step, the buttons start and stop the sequencer (sounds are scheduled, several at once), change the tempo, clear the grid and quit, and a pad click plays its drum. The roguelike page too: the tile sheet loads (64x8), keys and clicks play a turn without reaching the terminal, remembered tiles are darker, monsters chase and hurt, Esc closes the screen. Its music was checked too: the tune is read (37 notes, 21.8 s at 88 bpm), all its notes are scheduled and repeat, m stops and restarts it, and Esc stops it. Firefox and Safari are not tested.