λGTK: A PORTABLE GRAPHICS LAYER FOR COMMON MUSIC Heinrich Taube Composition/Theory School of Music University of Illinois Urbana, IL USA ABSTRACT presented an undue hardship or problem. But with the publication of Notes from the Metalevel [5] (the λGTK (LAMBDA GTK) is a new, portable graphics author’s book on algorithmic composition) in 2004, layer for implementing graphical user interface (GUI) new users who have no background in sound synthesis tools in Common Music [1] (CM), an algorithmic or programming have begun to experiment with music composition environment that runs in Common algorithmic composition and Common Music. The Lisp [2] and Scheme [3]. λGTK provides a complete author decided to use this recent circumstance as the interface to the popular GTK2 [4] graphics libraries and impetus to implement a graphic layer. Since CM is currently supports the development of graphical displays both portable and free, two central requirements of the in three different public domain Lisp implementations new graphics code are that (1) the graphics libraries on two different operating systems. Two full-featured must also be free and (2) the graphical tools that are GUI tools for Common Music -- a music data developed must be usable in more than one public visualization tool called Plotter and an executive “front domain Lisp implementation and on more than one end” window called CMIO -- are briefly described as operating system. After considering a number of examples of λGTK functionality. A key feature of different strategies and options the author decided to λGTK is that it is generated programmatically from base CM’s graphics on Version 2 of the Gimp Tool Kit information parsed from GTK header declarations rather (GTK2). GTK is a popular, public domain graphics than coded directly by hand. One benefit of this package that runs on multiple platforms, including implementation method is that larger (or less inclusive) Linux, OS X and Windows. Its powerful windowing interfaces can be generated on demand so Lisp features, free distribution, and stable release cycles make applications only need to load bindings for entry points it a good choice to implement source portable graphical in the GTK libraries that they actually use. Porting interfaces for Common Music. After first attempting to λGTK to new Lisp implementations is also much less use and adopt a few existing Lisp/GTK interfaces it work than if the layer had been coded by hand, and became apparent that there was no existing software that resolving errors and other porting issues is now a global offered a complete Lisp binding for the complete GTK2 operation (regenerating the layer) rather than a local one API or that would run on multiple operating systems (finding each affected entry and editing it by hand in a and Lisp implementations. Mario Momar’s LGTK [6] text editor). To port λGTK to a new Lisp the developer package was the best candidate system, but, because it simply provides “back end” functions to the generating is written by hand, it implements only a tiny fraction of program that translates the system’s intermediate Lisp the thousands of possible GTK entry points. After representation of GTK’s data structures into the considering the size of GTK and the fact that multiple appropriate foreign function interface (FFI) code for the bindings would be required for a portable layer, the new target host. The λGTK layer itself does not depend author decided that generating Common Music’s on anything in Common Music and is available as a graphics layer was the appropriate way to solve both separate, free software package released under the Lisp problems. Lesser General Public License (LLGPL). 2. λGTK DESIGN 1. BACKGROUND AND MOTAVATION Common Music is an object-oriented music λGTK is a cross-platform Lisp interface to the complete composition environment. It generates sound by GTK+2 family of shared libraries. Its design reflects transforming a high-level Lisp representation of musical solutions to two separate but equally problematic Lisp structure (algorithms, musical event descriptions and implementation issues: variability between different other compositional representations) into a variety of Lisp environments and the large number of GTK entry protocols for controlling sound synthesis and music points that a working Lisp interface might want to use. score generation. CM has bindings for both Common Most Lisp vendors provide a foreign function interface Lisp and Scheme dialects of Lisp and runs in a variety (FFI) protocol that specifies how Lisp programs can of Lisp implementations and operating systems. Its interface to non-Lisp (typically C) executables stored in highly portable nature, coupled with the fact that neither shared libraries. A number of Lisp implementations also Common Lisp nor Scheme requires a graphics standard, provide the ability for foreign code to call Lisp has made Common Music an essentially text-based functions encapsulated as foreign function callbacks. system until now. For a certain class of user – someone Any Lisp implementation that provides these two trained in musical synthesis languages or having prior features -- FFI linking to shared libraries and foreign programming experience – the lack of GUI tools has not function callback support -- is a candidate for using GTK2 as a windowing API. Happily, most Lisp implementations now fulfil these two essential pointers to ints, floats and doubles are also handled requirements in one way or another. Unfortunately, automatically: foreign values are allocated and because the Lisp language specification does not cover initialized on the Lisp side, the pointers are then foreign function interface design, the manner in which passed to GTK, dereferenced upon return and vendors implement these features varies widely with returned to the Lisp caller as multiple values. each Lisp implementation. In order to deal with this variability between Lisp FFI designs as well as with the • Lisp names for GTK's enums, structs and functions. sheer size of GTK’s programming interface (which Lisp names are formed by substituting "-" for "_" contains literally thousands of function, struct and enum and converting C library prefixes like glib_ and into exported Lisp package prefixes like definitions) λGTK contains no hand-coded software gtk_ beyond a handful of functions (ten) that implement glib: and gtk: (Figure 1). vendor specific “glue code” for creating and registering • Lisp accessor functions for reading and setting slot callbacks and allocating foreign structures. The rest of values in GTK structs. Struct slots that contain the interface -- currently consisting of 3,500 Lisp included structures are also supported, e.g. definitions for CM’s current graphics tools -- is gtk:widget.allocation.width. The first programmatically generated from two information argument to a Lisp foreign structure accessor is a database files. The first file (gtk.ffi) contains a Lisp pointer to the struct. If the referenced slot is an representation of all GTK library header declarations. array then a second required argument provides the The second file (gtk.api) is an API inclusion file that index. The final argument to a struct accessor is allows fine-grain control over which enums, structs, optional; if specified, it replaces the current value in struct slot accessors and API functions will receive Lisp the slot. For example: bindings in the generated interface. Both database files (gdk:rectangle.x rect) ; get x value (gtk.ffi and gtk.api) were derived from C header files (gdk:rectangle.x rect 100) ; set x value using FFIGEN [7], a program originally developed by Lars Thomas Hansen and now maintained by Gary Given the simple and consistent name translations, Byers as part of his OpenMCL [8] Lisp anyone who is familiar with GTK programming and implementation. FFIGEN uses output from the C Lisp function call syntax will find that graphics work compiler’s pre-processor to translate GTK header with λGTK is straightforward and requires no declarations into equivalent expressions formatted as documentation beyond the GTK API reference itself Lisp lists. These Lisp list expressions can then be read, (Figure 1). manipulated and analyzed by Lisp programs. In order to generate a GTK interface, λGTK reads the parsed header (gtk:define-signal-handler bye :void (w d) (format t "bye!~%") information contained in the gtk.ffi database and then (gtk:main-quit)) translates that information into the foreign function binding code for each supported Lisp implementation. (defun hello-world () The λGTK translation generator is organized into two (let ((w (gtk:window-new 0)) layers: a common file (lambda-gtk-common.lisp) and a (b (gtk:button-new-with-label "Hello World!"))) “back end” implementation file for each target FFI (gtk:container-add w b) (lambda-gtk-openmcl.lisp, lambda-gtk-cmucl.lisp, and (gtk:container-set-border-width w 10) so on). The translation program uses only a very modest (g:signal-connect w "destroy" set of features from its host Lisp environment and is (g:callback bye) (g:nullptr)) easily portable to any Common Lisp and reasonably (gtk:widget-show-all w) featured Scheme. λGTK currently generates GTK (gtk:main))) bindings for three different Common Lisp compilers on two different operating systems: Figure 1. The canonical “Hello World!” in λGTK. • OpenMCL 0.14.2-p on PPC/Darwin • SBCL [9] 0.8.16 on x86/Linux 4. COMMON MUSIC and λGTK • CMUCL [10] 19a on x86/Linux Two additional ports, to CLISP [11] on Windows XP λGTK provides Common Music with a portable and Guile Scheme [12] on x86/Linux, are in progress. graphics layer that behaves identically across different Lisp implementations and operating systems. Because 3. λGTK FEATURES λGTK is so new, the current release of Common Music contains only two GUI programs: a data visualization tool called Plotter, and a front end window, called The generated interface provides the following features CMIO, that facilitates algorithmic generation of musical to Common Music: material to and from the supported sound synthesis • Source portable GUI programming across the applications.