Nowadays, it seems that when I've got an idea for a new program I want to write for Linux, if I search the Net, someone's already published an open-source version of it. Such was the case recently when I thought it'd really be fun to have a graphical solitaire game for Microwindows. Entering Solitaire+Linux into the search engine gave me quite a few different implementations of Klondike, as well as an old favorite, FreeCell. Most of them were written for the X Windows System environment to be played on the Linux desktop. I figured that if I could find a well-written program based only on Xlib, it would be pretty straightforward to port it to the Nano-X API of Microwindows. And what do you know--third from the top of the list appeared xfreecell, a small, well-written freecell implementation based on Xlib. Porting xfreecell to Nano-X and going over the similarities and differences between the Xlib API and Nano-X API will be the subject of this month's column. The freecell source code is available at ftp://microwindows.org/pub/microwindows/nxfreecell-0.1.tar.gz.

Portability Concerns

Of course, there are quite a few concerns that need to be thought about when considering bringing a program built for the desktop over to an embedded environment. The program's overall structure, suitability for touch-screen rather than mouse input, size, graphical widget set used and external libraries required are some of the first things to look at. Most graphical programs written for X are either based on the low-level client graphics library, Xlib, or written on top of a much larger graphical applications toolkit like GTK+, Qt or FLTK. For the utmost smallest size, writing directly to the graphical windowing system's library will usually produce the smallest and quickest code, although there are tradeoffs. The low-level client libraries are exactly that--low level. Programs gain access directly to the drawing primitives that the windowing system provides. These include support for creating windows, drawing points, lines, polygons and filling areas. The windowing system handles drawings clipped to a given window and manages the window stacking view for the user. However, neither X nor Nano-X support the prebuilt, low-level widgets, like edit boxes and pushbuttons, that many desktop programs require. All of these have to be built on top of the low-level library, or a higher level applications toolkit must be used.

Xfreecell uses only low-level Xlib calls for all its drawing functions. The images for the playing cards are all specified as monochrome bitmaps in X11 format. These can be converted to Nano-X format with little effort. Xfreecell has a few dialog boxes and data input controls, but these are written directly on top of Xlib. The remaining portions of xfreecell handles event input, which is handled similarly between X and Nano-X.

Graphical windowing environments usually differ in their basic approach to how an application must be structured to work with the windowing environment. The design of Nano-X very closely follows the windowing and graphics drawing abstractions put forth by X. Although the Nano-X API isn't a reimplementation of X, most parameters for drawing functions have the same meanings. This approach was designed for a reason: if the API were exactly the same, then a reimplementation of X wouldn't likely be much smaller because most of the X server's code is there for a reason. In addition, folks are already working on making X smaller. The Nano-X implementation uses the same window and graphics abstractions as X but redesigns certain areas that are overly complex in X, like the color model, color maps and visuals. The result is a system that has many of the same capabilities as X and uses the same programming approach but is a lot less complex and quite a bit smaller.

In porting xfreecell, I decided that I would try leaving as much of xfreecell unmodified as possible, rather than changing the names of each drawing function, for instance. The result was the creation of the XtoNX.h header file, a set of C macros that greatly speed the process of porting a program from X to Nano-X. I'll go through each of the major sections of the header file as I explain the issues I found when porting xfreecell.

The first step was to produce a set of typedefs for making the X window, pixmap, region and other IDs compatible with Nano-X. With these declarations, various structures and data types used by X are made compatible without further modification, since windows, pixmaps, graphics contexts, regions and cursors are already abstractly compatible:

typedef GR_WINDOW_ID   Window;
typedef GR_WINDOW_ID   Pixmap;
typedef GR_GC_ID       GC;
typedef GR_FONT_ID     Font;
typedef GR_CURSOR_ID   Cursor;
typedef GR_REGION_ID   Region;
typedef GR_POINT       XPoint;
typedef GR_RECT        XRectangle;
typedef unsigned long  Time;

In order to ease porting, event and font structure typedefs were also created, although their member names aren't completely compatible. In this way, the compiler will accept the variable declarations and will later flag errors when member names are referenced incompatibly:

typedef GR_EVENT      XEvent;
typedef GR_FONT_INFO  XFontStruct;

Listing 1. Display Structure

Event handling is also very similar between the two graphical windowing environments, although the structure member names can't always be made compatible. Because of this, certain portions of the event handling code will have to be changed when porting to Nano-X. However, most of the events themselves are very similar, so we can add macros that define the correlation between similar events (see Listing 2).

Listing 2. Macros

The mechanisms for window creation, destruction, mapping, unmapping, raising, lowering, moving and resizing are mostly compatible, so a group of macros was created for these. However, the XOpenDisplay function needs to set up some global client data. In order to accomplish this, a STATIC_FUNCTIONS define was created that declares the static client XOpenDisplay function (see Listing 3).

Listing 3. STATIC_FUNCTIONS Define

Finally, a set of defines maps the low-level drawing functions from X to Nano-X (see Listing 4).

Listing 4. Set of Defines

Monochrome images in X and Nano-X can be specified as an array of bits, where each bit can be displayed in either the current foreground or background color. Xfreecell uses this mechanism to display each playing card. A monochrome bitmap is used to create a background pixmap for a window, and each playing card is created as a window using the automatic background pixmap feature to display the card image. The following call is used to associate a background pixmap with a window:

GR_WINDOW_ID pixid = GrNewPixmap(width, height, NULL); GrSetBackgroundPixmap(wid, pixid, flags);

The flags argument specifies how the pixmap is positioned in the background of the window. The following values are valid for the flag argument:

#define GR_BACKGROUND_TILE  0
        
#define GR_BACKGROUND_CENTER    1
        
#define GR_BACKGROUND_TOPLEFT   2
        
#define GR_BACKGROUND_STRETCH   4
        
#define GR_BACKGROUND_TRANS     8 /* Don't fill in gaps */

The GrNewBitmapFromData function allocates a GR_BITMAP-compatible array of bits from a passed bit array. In the last article (``Introduction to Microwindows Programming, Part 2'', ELJ March/April 2001), we showed how Nano-X supports images and h/w the GrBitmap function will draw a GR_BITMAP array of bits onto a window or pixmap using the current foreground and background colors. The GrNewBitmapFromData function is required because X and Nano-X don't store monochrome image bits in the same format. X stores monochrome images in a bit-reversed and byte-swapped format as compared to Nano-X. In addition, Nano-X requires the GR_BITMAP array to be short-word padded, where X allows no padding. Here's how this function can be used to convert X-style bitmap data for Nano-X:

GR_BITMAP *imagebits = GrNewBitmapFromData(width, GR_BMDATA_BYTEREVERSE|GR_BMDATA_BYTESWAP);

The width and height parameters specify the output width and height in pixels, while the bits_width, bits_height and bits parameters specify the input width, height and bit array. After creating a compatible bitmap array, the following new function uses it to create and initialize a pixmap:

GR_WINDOW_ID pixid = GrNewPixmapFromData(width, height, foreground, background, bits, flags);

After removing the #include <X11.h> defines and replacing them with #include <XtoNX.h>, most of the laborious conversion from X to Nano-X is done. I built the XtoNX.h header file to convert xfreecell, but there are quite a few more similar defines that might need to be added for helping convert the program you're working on. More defines can be added for the unreferenced X functions you encounter. However, there will still be a number of lines of code that can't be changed automatically with #defines. Some examples of this are covered below and include the event model, window manager communication and the color model.

The event model used by X, while similar to Nano-X, uses different member names and will need manual conversion. Xfreecell uses the .xany union to get a window id from an event structure. Nano-X currently requires that the requested event type be known. Thus, event processing code that looks like:

XEvent ev;
if (ev.xany.window == BUTTONID) ...

will need to be changed to:

if (ev.button.wid == BUTTONID) ...

The final area that differs greatly between X and Nano-X is the color model. The design of X allows user programs to take full advantage of widely differing hardware implementations for color representation. Microwindows and Nano-X, though, are designed to take advantage of the newer-style framebuffer access that's built into the Linux kernel. With Nano-X, colors are always specified as RGB values, regardless of the underlying hardware. Nano-X handles the conversion whether running on 8 bit-per-pixel palletized displays, or 16 or 32 bpp truecolor displays. While this sometimes costs in performance, it usually doesn't matter because embedded displays are quite a bit smaller than the displays used on desktops today. Also, X keeps a text file database of a huge number of named colors and values, where Nano-X either uses color schemes or direct RGB specification. Because of this, most color codes will have to be hand-converted. There's a considerable amount of code the X programmer has to write in order to convert from RGB, or named color values, to the currently used Visual, which requires hardware-dependent color values. You might find code like the following to obtain a color value:

Colormap cmap = DefaultColormap(display, 0);
XAllocNamedColor(display, cmap, "red" &c1, &c0); return c1.pixel;

This can all be replaced in Nano-X by:

#define MWINCLUDECOLORS
#include <nano-X.h>
return RED;

GR_RGB(255, 0, 0)

Converting programs built for one graphical windowing system to another can be quite complicated unless the systems are based around the same abstract model for windowing and graphics. The X and Nano-X windowing systems share the same abstraction for window creation, manipulation and drawing except for the color model, which is significantly easier to program for using Nano-X. Because of this, a macro header file can be used to lessen the porting effort from X to Nano-X. Using the XtoNX.h header file allowed porting xfreecell to Nano-X in a day or so, rather than starting from scratch. This brought another fun application to Microwindows and leveraged the open-source work of others. Stay tuned and try porting some applications yourself; it's fun and rewarding to create applications for embedded Linux devices!