λGTK: A PORTABLE GRAPHICS LAYER FOR COMMON MUSICSkip other details (including permanent urls, DOI, citation information)
This work is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 3.0 License. Please contact email@example.com to use this work in a way not covered by the license. :
For more information, read Michigan Publishing's access and usage policy.
Page 00000001 XGTK: A PORTABLE GRAPHICS LAYER FOR COMMON MUSIC Heinrich Taube Composition/Theory School of Music University of Illinois Urbana, IL USA ABSTRACT XGTK (LAMBDA GTK) is a new, portable graphics layer for implementing graphical user interface (GUI) tools in Common Music  (CM), an algorithmic music composition environment that runs in Common Lisp  and Scheme . XGTK provides a complete interface to the popular GTK2  graphics libraries and currently supports the development of graphical displays in three different public domain Lisp implementations on two different operating systems. Two full-featured GUI tools for Common Music -- a music data visualization tool called Plotter and an executive "front end" window called CMIO -- are briefly described as examples of XGTK functionality. A key feature of XGTK is that it is generated programmatically from information parsed from GTK header declarations rather than coded directly by hand. One benefit of this implementation method is that larger (or less inclusive) interfaces can be generated on demand so Lisp applications only need to load bindings for entry points in the GTK libraries that they actually use. Porting XGTK to new Lisp implementations is also much less work than if the layer had been coded by hand, and resolving errors and other porting issues is now a global operation (regenerating the layer) rather than a local one (finding each affected entry and editing it by hand in a text editor). To port XGTK to a new Lisp the developer simply provides "back end" functions to the generating program that translates the system's intermediate Lisp representation of GTK's data structures into the appropriate foreign function interface (FFI) code for the new target host. The XGTK layer itself does not depend on anything in Common Music and is available as a separate, free software package released under the Lisp Lesser General Public License (LLGPL). 1. BACKGROUND AND MOTAVATION Common Music is an object-oriented music composition environment. It generates sound by transforming a high-level Lisp representation of musical structure (algorithms, musical event descriptions and other compositional representations) into a variety of protocols for controlling sound synthesis and music score generation. CM has bindings for both Common Lisp and Scheme dialects of Lisp and runs in a variety of Lisp implementations and operating systems. Its highly portable nature, coupled with the fact that neitherCommon Lisp nor Scheme requires a graphics standard, has made Common Music an essentially text-based system until now. For a certain class of user - someone trained in musical synthesis languages or having prior programming experience - the lack of GUI tools has not presented an undue hardship or problem. But with the publication of Notes from the Metalevel  (the author's book on algorithmic composition) in 2004, new users who have no background in sound synthesis or programming have begun to experiment with algorithmic composition and Common Music. The author decided to use this recent circumstance as the impetus to implement a graphic layer. Since CM is both portable and free, two central requirements of the new graphics code are that (1) the graphics libraries must also be free and (2) the graphical tools that are developed must be usable in more than one public domain Lisp implementation and on more than one operating system. After considering a number of different strategies and options the author decided to base CM's graphics on Version 2 of the Gimp Tool Kit (GTK2). GTK is a popular, public domain graphics package that runs on multiple platforms, including Linux, OS X and Windows. Its powerful windowing features, free distribution, and stable release cycles make it a good choice to implement source portable graphical interfaces for Common Music. After first attempting to use and adopt a few existing Lisp/GTK interfaces it became apparent that there was no existing software that offered a complete Lisp binding for the complete GTK2 API or that would run on multiple operating systems and Lisp implementations. Mario Momar's LGTK  package was the best candidate system, but, because it is written by hand, it implements only a tiny fraction of the thousands of possible GTK entry points. After considering the size of GTK and the fact that multiple bindings would be required for a portable layer, the author decided that generating Common Music's graphics layer was the appropriate way to solve both problems. 2. XGTK DESIGN XGTK is a cross-platform Lisp interface to the complete GTK+2 family of shared libraries. Its design reflects solutions to two separate but equally problematic Lisp implementation issues: variability between different Lisp environments and the large number of GTK entry points that a working Lisp interface might want to use. Most Lisp vendors provide a foreign function interface (FFI) protocol that specifies how Lisp programs can interface to non-Lisp (typically C) executables stored in shared libraries. A number of Lisp implementations also provide the ability for foreign code to call Lisp functions encapsulated as foreign function cal/backs. Any Lisp implementation that provides these two features -- FF1 linking to shared libraries and foreign function callback support -- is a candidate for using GTK2 as a windowing API. Happily, most Lisp
Page 00000002 implementations now fulfil these two essential requirements in one way or another. Unfortunately, because the Lisp language specification does not cover foreign function interface design, the manner in which vendors implement these features varies widely with each Lisp implementation. In order to deal with this variability between Lisp FFI designs as well as with the sheer size of GTK's programming interface (which contains literally thousands of function, struct and enum definitions) XGTK contains no hand-coded software beyond a handful of functions (ten) that implement vendor specific "glue code" for creating and registering callbacks and allocating foreign structures. The rest of the interface -- currently consisting of 3,500 Lisp definitions for CM's current graphics tools -- is programmatically generated from two information database files. The first file (gtk.ffi) contains a Lisp representation of all GTK library header declarations. The second file (gtk.api) is an API inclusion file that allows fine-grain control over which enums, structs, struct slot accessors and API functions will receive Lisp bindings in the generated interface. Both database files (gtk.ffi and gtk.api) were derived from C header files using FFIGEN , a program originally developed by Lars Thomas Hansen and now maintained by Gary Byers as part of his OpenMCL  Lisp implementation. FFIGEN uses output from the C compiler's pre-processor to translate GTK header declarations into equivalent expressions formatted as Lisp lists. These Lisp list expressions can then be read, manipulated and analyzed by Lisp programs. In order to generate a GTK interface, kGTK reads the parsed header information contained in the gtk.ffi database and then translates that information into the foreign function binding code for each supported Lisp implementation. The XGTK translation generator is organized into two layers: a common file (lambda-gtk-common.lisp) and a "back end" implementation file for each target FFI (lambda-gtk-openmcl.lisp, lambda-gtk-cmucl.lisp, and so on). The translation program uses only a very modest set of features from its host Lisp environment and is easily portable to any Common Lisp and reasonably featured Scheme. XGTK currently generates GTK bindings for three different Common Lisp compilers on two different operating systems: * OpenMCL 0.14.2-p on PPC/Darwin * SBCL  0.8.16 on x86/Linux * CMUCL  19a on x86/Linux Two additional ports, to CLISP  on Windows XP and Guile Scheme  on x86/Linux, are in progress. 3. XGTK FEATURES The generated interface provides the following features to Common Music: * Source portable GUI programming across the supported Lisp environments. * Automatic conversion between Lisp data types (booleans, numbers, strings) and their equivalent types in GTK. Function arguments that involve C pointers to ints, floats and doubles are also handled automatically: foreign values are allocated and initialized on the Lisp side, the pointers are then passed to GTK, dereferenced upon return and returned to the Lisp caller as multiple values. * Lisp names for GTK's enums, structs and functions. Lisp names are formed by substituting "-" for "_" and converting C library prefixes like glib_ and gtk_ into exported Lisp package prefixes like glib: and gtk: (Figure 1). * Lisp accessor functions for reading and setting slot values in GTK structs. Struct slots that contain included structures are also supported, e.g. gtk: widget. allocation.width. The first argument to a Lisp foreign structure accessor is a pointer to the struct. If the referenced slot is an array then a second required argument provides the index. The final argument to a struct accessor is optional; if specified, it replaces the current value in the slot. For example: (gdk:rectangle.x rect);get x value (gdk:rectangle.x rect 100);set x value Given the simple and consistent name translations, anyone who is familiar with GTK programming and Lisp function call syntax will find that graphics work with XGTK is straightforward and requires no documentation beyond the GTK API reference itself (Figure 1). (gtk:define-signal-handler bye:void (w d) (format t "bye!~%") (gtk:main-quit)) (defun hello-world () (let ((w (gtk:window-new 0)) (b (gtk:button-new-with-label "Hello World!"))) (gtk:container-add w b) (gtk:container-set-border-width w 10) (g:signal-connect w "destroy" (g:callback bye) (g:nullptr)) (gtk:widget-show-all w) (gtk:main))) Figure 1. The canonical "Hello World!" in XGTK. 4. COMMON MUSIC and XGTK XGTK provides Common Music with a portable graphics layer that behaves identically across different Lisp implementations and operating systems. Because XGTK 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 CMIO, that facilitates algorithmic generation of musical material to and from the supported sound synthesis applications. These two windows are full-featured interfaces and require entry points into most of the libraries, from high-level GTK widget sets to low-level GDK drawing primitives and GLIB event/signal handlers. CM's graphics code requires no compile time conditionals to account for any differences between the
Page 00000003 bindings. Just as importantly, since the bindings are generated, additional entry points into the GTK libraries can be included in the future without any additional work by the author as GUI tools are added and developed. 5. CMIO The CMIO (Common Music Input/Output) window (Figure 2) provides a graphical "front end" for Common Music. Its primary purpose is to facilitate the most common compositional activities apart from algorithmic design: configuring synthesis and playback options and generating musical event data to-and-from the supported sound synthesis and display applications. In addition, the CMIO window provides users with a concise, high level, top-down view of the system's complete IO capabilities, which means that new users can acquaint themselves with the overall design of the CM system quite quickly. CMIO windows also offer the new user a structured alternative to evaluating input and output expressions inside the Lisp read-eval-print loop (REPL). The CMIO window performs its own Lisp error handling and, by default, reports Lisp errors without triggering the Lisp debugger. This more "gentle" approach to error handling allows novice users to experiment with algorithmic composition and sound rendering examples with little or no prior experience with Lisp, without having to deal with input and output command evaluation inside Lisp's development REPL. Figure 2. The CMIO window with the MIDI files page selected as the current target. A Status line displays color-coded messages about 5.1. Window Layout ongoing actions in the window. The CMIO interface consists of four GUI components arranged from top to bottom in the window: * A Sources notebook holds tabbed notebook pages that relate to creating and generating event data. * A Targets notebook holds tab pages related to sound synthesis and display applications. * An Executive frame manages the system's current working directory and current target file. Each tabbed page in the window contains a set of fields representing the input/output features of a given application or task. The right-justified pages (such as Help or Systems) control more general features of the window or the surrounding Lisp environment. Color highlighting provides visual clues as to how information on a page is interpreted by the interface: * Blue labels mark fields that must contain information before a page can execute.
Page 00000004 * Yellow backgrounds mark fields that will be explicitly evaluated by Lisp when the information is accessed. * White backgrounds indicate fields that contain either uninterpreted text or else are read by Lisp to produce a value. It is possible to force evaluation in a white field using the notation #.expr, where expr is a Lisp expression that, when accessed by the interface, will be evaluated to produce the contents of the field. * The Status line uses colors to classify the type of message displayed: green text represents normal information, yellow indicates a warning or notification, and red signifies an error condition. 5.2. Using the CMIO Window To render musical events to a sound application, the user selects and configures the target's application page then enters an event expression in the Events buffer and clicks the Compose button. Each target application page has numerous fields for customizing its specific IO behavior. These fields can be set in the GUI and also initialized to the user's preference when the window is created. The exact set of sound applications (labeled targets in the window) that are available at any given time depends both on what programs are installed on the host computer and what software systems have been loaded into Lisp. These sound systems do not need to be configured ahead of musical experimentation; the window's Systems and Files pages permit external software applications such as CLM, CMN and Midishare to be dynamically configured and loaded at any appropriate point in the working process. 6. PLOTTER Plotter is a graphical tool for displaying, editing and sequencing musical data. This data can be passed to a Plotter window in two different external formats: lists ofxy breakpoint values and lists of CLOS  objects. When breakpoints are specified the window becomes a full-featured envelope editor for creating breakpoint collections for use in shape-based composition and sound synthesis (Figure 3). When lists of CLOS objects are passed to a Plotter window it can serve as a generalized music sequencer for searching, editing, creating and playing back musical material (Figure 4). Any number of Plotter windows can be open at the same time, and copy/pasting between windows is supported. It is also possible to manipulate Plotter windows (and the data inside them) by calling Plotter's API functions remotely from the Lisp REPL process. 6.1. Displays, Axes, Layers and Points A Plotter window provides a two-dimensional view onto one or more sets of point data. Point sets are grouped into displays where each display defines a particular mapping of data to its graphic presentation in the window. A display's basic visual characteristics are controlled by axis objects that determine which slots in the data sets are plotted and how these values will be mapped to the display's presentation. Each axis can control up to two slots of data, so a total of four slots of interest can be viewed as the horizontal, vertical, width, and height properties of the graphic points drawn in the window. The user assigns axis slots when the window is created and may change the slot assignments after the window is open. Since the slot assignments are the only connection between the display's presentation and the data, Plotter is capable of graphing any object represented in the CLOS object system. Within a single display each data set is drawn in its own layer. Plot editing takes place on the front-most layer; background layers can be brought forward by clicking on their points or by selecting the layer from a pop-up menu. Layers can be made transparent, invisible or opaque. If a layer is transparent then the data sets behind it are also visible. If a layer is made invisible then its data will not appear in the display until it is explicitly made visible again. Depending on how the display axes are defined, each layer can switch between six basic viewing styles: Line and point, Line, Point, Bar, Box and Bubble. An additional Notation view is currently under design. 6.2. Plotter Tool Windows Plotter Tool windows facilitate specific tasks when working in a Plotter display. Tool windows belong to the Potter they affect and are automatically closed when the Plotter window itself is closed. There are currently three tool windows defined: Sizing, Zooming, and the Editing tool. These windows all operate interactively; changing a setting on them immediately updates the main window display without having to click an OK or Cancel button. The Sizing tool allows the size and style of points and lines to be controlled. The Zooming tool allows both Zoom to Fit and percentage zooming from.25% to 400%; zooming can be applied to either or both axes independently and can affect the size of lines and points or not. The Editing tool contains three tabbed displays: Cursor Mode, Selecting, and Mouse Control. The Cursor Mode page toggles between four possible editing modes: Select Points, Select Regions, Add Points and Delete Points. Each mode is indicated by an appropriate cursor in the Plotter display. The Select points pages allows selection expressions to be evaluated. This is a very powerful editing feature because it enables only those points for which an arbitrary predicate test returns true to be selected for editing. The Mouse Controls tab allows various aspects of mouse behavior to be controlled, including the ability for the user to set an Add Points hook (function) that will be called whenever a point is added by a mouse click the display. The hook function can return whatever objects it wants to. Hooks to compute chords by FM synthesis and ring modulation are provided by Common Music.
Page 00000005 It UP cIQ UP CD+ a7......................................................................................................................................................................................................................................................................... J IJ ru t I I I I I CD J C C 0 _ 0 0 0 on -0. 111 C,....................................................................................................................................................................................I x............. /........................................\...............................................................................................................
Page 00000006 7. FUTURE DIRECTIONS The XGTK graphics layer is essentially complete. Future directions include porting the layer to CLISP on Windows XP, and to Guile Scheme on Linux. The process of designing interface tools for Common Music has just begun and will be the central focus of software development for some time. Future plans include implementing a pattern editing tool, a Common Practice notation view for Plotter data, and a Code editor for experimenting with musical algorithms. 8. CONCLUSION Common Music is an algorithmic composition system that runs in a variety of Lisp implementations and operating systems. Its highly portable code base has, until now, limited users of the system to text-based interactions. XGTK is a new graphics layer for Common Music that supports GUI design using the popular GTK widget libraries. XGTK code is generated from GTK's header declarations in order to simply many implementation and porting issues. Despite its recent development, the new graphics layer already supports two full-featured GUI tools that are source portable across three different Lisp implementations and two operating systems. Future plans include porting XGTK to CLISP on Windows XP and Guile Scheme, and to continue developing new GUI tools for algorithmic composition in Common Music. 9. REFERENCES Taube, H., "Common Music: A Music Composition Language in Common Lisp and CLOS", Computer Music Journal, 1991. 15(2): p. 21-32. Steele, G., Common Lisp the Language, 2nd edition. Digital Press, Wobern, 1990.  Steele, G., Common Lisp the Language, 2nd edition. Digital Press, Wobern, 1990.  Clinger, W., Kelsey, R. and Rees, J. (eds.), "Revised (5) Report on the Algorithmic Language Scheme", Higher-Order and Symbolic Computation, August 1998. 11(1).  "GTK+ The Gimp Toolkit", Reference Manual web page, <http://devel noer ordc AP/2gt  Taube, H. Notes from the Metalevel, an Introduction to Algorithmic Composition. Tayor and Francis, London, 2004.  Momar, M. "LGTK - GTK bindings for Common Lisp", Project home page, <hLttp~:iiomon-lisi.net/proi et tk/->.  Hansen, L. "FFIGEN Manifesto and Overview", Web page, <htt:i//iwww.ccs.net..e/ediho/ime/thifi/fniaeifesto. htm>.  Byers, G. "OpenMCL Common Lisp", Project home page, <htt- // ren ncl.cl 1 ozuare. com-in id x htuml>.  Rhodes, C. et al. (developers). "Steel Bank Common Lisp", Project home page <h:tt /i//Lwww. Sbc 1^ o '. Cracauer, M. et al. (developers). "CMUCL: a high-performance, free Common Lisp Implementation," Project home page, http://www Conl s.ogrZiC ucTli Haible, B. and Steingold, C. "GNU CLISP", Home page, <httii clis^nsor>. 'Guile Scheme, Project GNU's extension language", Home page, <htt ):/ vww.w Y inu.or f re cuile/>. [13 ]Keene, S. Object-Oriented Programming in Common Lisp. A Programmer's Guide to CLOS. Addison-Wesley, Reading, 1989.