Introduction

The GUIDOLib project aims at the development of a generic, portable library and API for the graphical rendering of musical scores. The library is based on the GUIDO Music Notation format as the underlying data format. It is an open source project covered by the Mozilla Public License.

The project has started in December 2002, based on the source code of the GUIDO NoteViewer developed by Kai Renz.

The GUIDO Music Notation

The GUIDO Music Notation format (GMN) is a general purpose formal language for representing score level music in a platform independent plain text and human readable way. It is based on a conceptually simple but powerful formalism: its design concentrates on general musical concepts (as opposed to graphical features). A key feature of the GUIDO design is adequacy which means that simple musical concepts should be represented in a simple way and only complex notions should require complex representations.

The GMN language is fully documented on the guidodoc web site.

The GUIDO Engine

The GUIDO Engine operates on a memory representation of the GMN format: the GUIDO Abstract Representation (GAR). This representation is transformed step by step to produce graphical score pages. Two kinds of processing are first applied to the GAR:

GAR to GAR transformations which represents a logical layout transformation: part of the layout (such as beaming for example) may be computed from the GAR as well as expressed in GAR,
the GAR is converted into a GUIDO Semantic Normal Form (GSNF). The GSNF is a canonical form such that different semantically equivalent expressions have the same GSNF.

This GSNF is finally converted into a GUIDO Graphic Representation (GGR) that contains the necessary layout information and is directly used to draw the music score. This final step includes notably spacing and page breaking algorithms.

Note that although the GMN format allows for precise music formatting (in advanced GUIDO), the GUIDO Engine provides powerful automatic layout capabilities.

Main library services

The main services provided by the library are:

Score layout: the library provides functions to parse a GMN file and to create the corresponding GAR and GGR.
Score pages access: result of the score layout is a set of pages. The library provides the necessary to change the page size, to query a score pages count, the current page number or the page number corresponding to a given music date.
The GUIDO Factory: the GUIDO Engine may be feeded with computer generated music using the GUIDO Factory. The GUIDO Factory API provides a set of functions to create a GAR from scratch and to convert it into a GGR.
Mapping: along with the GGR, the GUIDO Engine maintains a tree of graphical music elements. Each element has a bounding box and a date. The library includes the necessary to browse this tree and to retrieve elements by date or position.

Graphic devices

First version of the GUIDO Engine was Windows dependent: a Windows HDC type (graphic device context handle) was provided to the GGR objects, that were directly calling Microsoft Windows APIs to draw graphics and text.

For the GUIDO Engine to be platform-independent, and to avoid being restricted to one graphical technology (even a cross-platform one such as pdf, eps or OpenGL ...), the choice has been made to provide a C++ object (called VGDevice) to the GGR objects, in place of the previous windows HDC handle.

VGDevice is a C++ pure virtual class that declares all methods required by the GGR objects to communicate their graphical operations. Implementations of VGDevices are provided by clients applications using derived classes so that neither GGR objects nor any part of the GUIDO Engine depends on a particular graphical implementation.

The main advantage is that VGDevice derived classes can implement any kind of graphic output: on-screen (platform specific, OpenGL), off-screen (raw bitmaps), files (pdf, svg, postscript), network streams...

VGDevices derived classes must provide standard graphic functions (Lines, Arcs, Boxes,Polygons, Text), coordinate transformations (zoom / scaling), and symbolic music symbols handlers (DrawSymbol method). VGDevice design makes a clear distinction between text characters and music symbols (although music symbols are generally glyphs in a music font). Music symbols are identified by font-independent constants. This mechanism provides VGDevice objects with a higher abstraction level than a pure graphic layer.

Existing implementations of VGDevices:

    GDeviceOSX:             MacOS X Quartz implementation.
    GDeviceWin32:           Windows (gdi)
    GDeviceWin32GDIPlus:    Windows (gdiplus)
    CairoDevice:            Linux   (cairo)
    GDeviceQt:              platform independent - Qt based device
    GDeviceGL:              OpenGL implementation

Unsupported VGDevice implementations:

    GDeviceWin2000:         Windows 2000 / XP(gdi+)
    GDeviceGTK:             Linux GTK implementation
    GDevicePostScript:      EPS files (encapsulated postscript)
    GDeviceWx:              wxWindows DC implementation.