LibGGI: Yet Another Graphics API

We didn't like the idea of another graphics library, but when we checked the available solutions at the time the GGI project was initiated, we found nothing that would fit all our needs:

First of all, portability is our only weapon against the commercial software market. If we are so portable that we can run on any platform, including the mainstream market, we might be able to get those nice programs, because it is no problem to port them.

The X Window System is about as portable as a program gets and X applications are normally fairly portable. However, using X is often overkill and causes considerable overhead. Moreover, writing X programs is rather difficult (depending on which toolkit you use) and seems really alien to most non-UNIX gurus.

However, X is the most important platform in the UNIX world and, to call ourselves portable, we need to support X. LibGGI uses a system of dynamically loadable target drivers that allow it to run on anything with the ability to display graphics. It does not make a difference if the display target is some type of server software, a KGI-like device, something directly accessing graphics hardware, a printer, a system-service of a microkernel OS or something else. Table 1 shows a few available target systems that LibGGI programs can run on.

Graphics-server systems:

Device-oriented systems:

LibGGI detects the most desirable target available on the current hardware and automatically makes use of it. This can be overridden to force different behaviour easily.

Compatibility is maintained at binary level within one platform. That is, a LibGGI application compiled for Linux x86 will run without modification on a KGI full screen, in an X window, using SVGAlib or GLIDE. It will even run on a text-mode screen via LibAA or whatever is available.

Compatibility across platforms requires a recompile, but this should be painless if the surrounding code doesn't heavily use OS specifics.

So, porting applications is easy. But what about porting LibGGI itself? We have tried keep LibGGI as portable as possible. Most GGI code compiles without a warning in gcc -pedantic mode. We have also tried to keep use of OS specifics to a bare minimum.

LibGGI should build easily on any system that has heard of POSIX. Even libdl isn't strictly required anymore to allow for systems that don't recognize dynamic libraries.

Another important point in the design of LibGGI is simplicity. If a programmer just wants to write a small graphics utility, he may be scared off by the complexity of X. To give you an idea of how programming with LibGGI works, let's look at the small example program shown in Listing 1.

It doesn't show good style, but is designed to be straightforward to read. As with any library, you have to include its headers. These are located in a subdirectory. Since we have more than one library, we decided that allocating a whole subdirectory would cause less confusion.

The first thing you have to do when using LibGGI is call ggiInit. This initializes the LibGGI internal data structures and sets up everything. Next, you call ggiOpen. This call returns a ggi_visual_t which is an opaque type, similar to what X calls a “drawonable”. Think of it as an abstract handle to the display you draw on. Note that you can have multiple displays per program as required by complex applications which handle multiple screens.

You will want to set a graphics mode on the visual. A mode consists of the size, or rather, resolution of the visible area (visx, visy) as well as that of the virtual area (virtx, virty) on which the view port can be panned around. Moreover, you need to specify the type of display you request; for example, a GT_24BIT true color visual. Note that calls to request additional options are available, as well as the capability to automatically choose values. This is highly recommended in order to enhance portability.