Entwined in the Entrails

Technical Information about W

One main goal of W is easy graphics programmability. That has been achieved with sensible default values, easy server connection / window initialization, and server based window backups. The last one will (on cost of memory) ease server clipping and lessen the network load.

W server
W library
W Toolkit (optional)
W graphics pipeline

W1R4-beta code size is about:

		lines		  KB
------------------------------------
W server	20000		 550
W library	 6000		 130
W toolkit	22000		 450
------------------------------------
		48000		1130

Applications have about the same size all together.

About half of the W server code is for the low level graphics routines needed with different screen formats in the W server.

W server

W server is composed of the initialization code which handles terminal and signals, initializes screen, functions accessing it and W server socket, reads configuration and acts on it. The main loop handles the windows, redraws and menu + of course invokes server functions according to the CLIENT requests.

The graphics drivers are in a library that is linked to the W server binary. At the startup the OS/HW specific graphics initialization function, based on the current graphics mode, sets the screen properties (might also first change into some precompiled graphics mode) into SCREEN struct and selects which driver functions will be used i.e. returns a pointer to a suitable SCREEN graphics function pointer table structure.

Currently there are initialization routines for Atari MiNT, 68k-Linux (Atari / Amiga), SunOS, Amiga NetBSD and x86-Linux. Of them the Atari graphics modes are best supported because all the three main developers have ATM an Atari (others modes are tested on university machines or done by other people on the W development mailing list). In any case the two-color nature of the W server kind of nullifies arguments for the high/True Color mode drivers.... The graphics types supported are:

One bitplane bitmap. Big-endian byte order (packed, MONO driver). Memory wise this would be the wisest choice as windows are backed up by the server.
Interleaved bitmaps, of which only two bitplanes are used. Big-endian byte order (packed, COLORMONO driver). This is faster than the COLOR driver (on graphics devices where bitplanes are on separate bitmaps, monochrome driver could be used instead if processor allows long accesses on word boundaries).
Interleaved bitmaps with palette. A special array is used to determine which plane(s) need to be set for the back/foreground colors. Big endian byte order. (packed, COLOR driver).
8-bit, chunky bitmap with palette (direct-8, COLOR driver).

With the COLOR drivers the (two) window colors are selectable. Interleaved bitplanes contain the first 16 pixels on first bitplane, then the same pixels on next bitplane and so on until the next 16 pixels on the first bitplane, then same pixels on the next bitplane etc.

All of the drivers need graphics memory to be linearly accessible. For example on x86 PCs most(?) Super VGA modes / graphics cards use paged memory. The standard 640x480x16 VGA resolution doesn't need paging though (it can be set which bitplanes are written to before changing the bitmap), so supporting it would need 'just' converting the monochrome driver to use little-endian byte order and making up a suitable initialization routine. Any volunteers?

Screen memory

Under MiNT the screen memory block address is acquired by XBios call for the logical screen address. On unix machines the frame buffer device is mmap()'ed to memory or some additional library is used for acquiring a 'screen'. Then the graphics functions just write to the returned bitmap address.

W library

W library takes care of marshaling (packaging arguments into structs before sending them over network for unmarshalling) function calls, buffering the graphics requests, and some utility functions. Besides socket buffering, a lot of the W library code has gone / will go to the routines that deal with w_get/putblock() functions as W server might be in a different graphics mode from the one used by the client bitmaps and therefore numerous conversion and alignment routines are needed. Other utilities include a simple button gadget implementation and loading of RLE packed images (GEM IMG format).

W Toolkit

Kay Römer has created a W toolkit that is similar to the X toolkit. With it user can create user interface component hierarchies in an object-oriented manner. The user interface components are called 'widgets'. A widget can be a simple (referring to hierarchy, not code size) one like scrollbar, button or fileselector or it can be a container like shell (W window), viewport (scrollable area) or pane (arranges child widgets horizontally or vertically).

User can attach callback functions to widgets which will be invoked when a certain widget specific action is performed (for example button widget is clicked). There can also be timer and file event callbacks.

After user has created the widget hierarchy/ies and put it/them onto the screen he gives the application control over to the toolkit which will then call the user functions as needed. This way handling the user input is easier and more consistent. Extending and changing the user interface will also be much easier as there are lots of ready made interface components already available. Even complex ones like fileselector, HTML and terminal widgets.

As there isn't (yet) a Wt user interface builder, the widget hierarchies have to be built 'by hand' and tested by compiling the code. After some experimenting with the toolkit this shouldn't be much of a hindrance as long as one keeps the widget manuals (listing the widget options) at hand. :-)

The W graphics 'pipeline':

W TOOLKIT

Layout and draw the widgets onto container windows.
Check for incoming W and file events and timeouts.
Call the widget's handler for that event.

...Calls Wlib function(s)...

WLIB

Function argument validity is tested.
graphics request packet is composed.
packet is copied to the socket buffer.

... when buffer fills up or user requests an event, buffer contents are 'bulk'-sent to ...

WSERVER

Stuff on the socket is read into socket buffer.
Request packet is extracted from the socket buffer.
Request process function is called with the client pointer and window handle.
Window pointer is looked up from hash table based on the window handle.
Different window based attributes are set (graphics context, clipping rectangle).
Window partially visible or -DREFRESH compilation option used:
Graphics are drawn to the window backup.
The window 'dirty' (changed part) rectangle is updated.
When the socket buffer doesn't contain any more packets to process or there's a query event, the 'dirty' area(s) will be flushed onto the screen.
Window on top or fully visible:
If graphics would come under mouse, mouse will be disabled.
Graphics are drawn to the window and window is marked as 'dirty'.
When another window is topped, the contents of the 'dirty' window are copied from screen to the window backup.

puujalka@modeemi.cs.tut.fi