Saturday, 02 January 2021
SDL2 - Jim Tcl sdl extension update
Since the early days of Jim Tcl, the included sdl extension has provided an example of how to integrate an external library as a Jim Tcl extension.
However this extension had not been updated for some time, and did not support the newer SDL2 API.
Now the sdl extension has been updated to support both SDL and SDL2, and also includes some additional features.
Building the extension
configure uses pkg-config to find the required libraries, so be sure to have SDL2_gfx (and optionally SDL2_ttf) installed where pkg-config can find them.
$ pkg-config --modversion SDL2_gfx 1.0.2
Build the sdl extension as a module by specifying it at configure time.
$ ./configure --full --with-mod=sdl ... Checking for SDL2_gfx ...1.0.2 Checking for SDL2_ttf ...2.0.15 Extension sdl...module ... $ make ... CC jim-sdl.o LDSO sdl.so ...
Testing the extension
Some test scripts are available in the examples/ directory.
$ ./jimsh examples/sdltest.tcl
$ ./jimsh examples/sdlevents.tcl
Using the extension
Create a window (sdl screen) with the sdl.screen
command
. package require sdl 1.0 . set s [sdl.screen 640 480 "Window Title"] ::sdl.surface4
The returned handle provides a number of subcommands. Help is available for each subcommand.
. $s -commands free flip poll clear pixel circle aacircle fcircle rectangle box line aaline font text . $s -help fcircle Usage: ::sdl.surface4 fcircle x y radius red green blue ?alpha? . $s fcircle 100 100 30 200 0 0 . $s flip
Colours in SDL use separate red, green and blue components. These are specified as integers from 0 to 255. Similarly, the alpha (opacity) is specified from 0 (transparent) to 255 (opaque).
The image commands are as follows:
clear
- clear the entire window to the given colourpixel
- draw a single pixelcircle
- draw a circle (outline)aacircle
- draw a circle (outline) with antialiasingfcircle
- draw a filled circlerectangle
- draw a rectangle (outline)box
- draw a filled rectangleline
- draw a lineaaline
- draw a line with antialiasing
If the SDL2_ttf package is available, basic text support is also provided.
font
- load a TrueType font from a file with the given point sizetext
- draw text with the currently loaded font
Some notes on text:
- Only one font may be loaded at a time
- The specified font may not support all unicode glyphs.
- To display utf-8 text, Jim Tcl must have been built with –utf8
There are several non-drawing commands.
free
- close the window and free the handle (the same as:rename $s ""
)flip
- update the window to match graphics changes, then clear the background buffer and poll for eventspoll
- update the window to match graphics changes, then poll for events
Note that the graphics window is double (or triple) buffered. This means that any
graphics changes are not displayed until flip
or poll
is used.
In general, you should display an entire frame and then call flip
.
In order to keep the SDL window responsive, it is necessary to pump the SDL event loop.
Both flip
and poll
can be used for this. Currently the only SDL event that is recognised is the SDL_QUIT event.
When this event occurs, flip
and poll
return JIM_EXIT. By default, this will exit the interpreter.
A typical script that simply displays a single image will look like:
... draw the SDL image ... $s poll { sleep 0.25 }
This will run the SDL event loop and then eval the given script. If SDL_QUIT is ever received, the script will exit.
See examples/sdlevents.tcl
for an example of how to integrate the SDL event loop
with the Jim Tcl event loop.
Steve Bennett (steveb@workware.net.au)
comments powered by Disqus