7 Graphics Driver Interface

 7.1 Anatomy of a Window
 7.2 Drawing in the Window
 7.3 Drawing in the Overlay Plane
 7.4 The Colour Table
 7.5 Scrolling
 7.6 Examples
 7.7 Subroutine Specifications

This section describes the routines that are used by low level graphics software to interact with GWM windows. A working knowledge of Xlib programming is assumed.

The routines described here are for the use of “system” software only and all this information in this section is subject to change without notice. Therefore before making any use of it you should consult the Starlink project staff at RAL.

These return a status value rather than reporting errors; symbolic names for the status values can be found in gwm_err.h. Note that these are not EMS error codes.

7.1 Anatomy of a Window

A GWM window consists of the following components:

Various items of information are stored as properties of the window so that any applications which knows the id of the window can read and write them. The GWM_SetXxxx and GWM_GetXxxx routines can be used to access them. The properties are:

GWM_background
The background colour of the window (a character string)
GWM_colour_table
An array of integers that lists the colour cells allocated to the window. The first element of the array defines the background colour.
GWM_foreground
The foreground colour of the window (a character string)
GWM_name
The window name (a character string). This enables a window id to be translated into a GWM window name.
GWM_ov_mask
A bit mask that which plane is the overlay plane. The mask has a 1 in every bit position that should be used when writing to the window and a 0 in the bit position corresponding to the overlay plane. A window with no overlay plane has a mask of all 1s.
GWM_pixmap
The id of the pixmap.
GWM_x_offset GMW_y_offset
The position of the top left corner of the pixmap relative to the top left corner of the window. Used by the refresh process when copying the pixmap to the window and allows the contents of the window to be scrolled.
GWM_x_ov_offset GWM_y_ov_offset
As above but for the overlay plane.

7.2 Drawing in the Window

Everything drawn in the window must also be drawn in the pixmap so that the window is refreshed properly. The easiest way to do this is to draw into the pixmap first and then add the x and y offsets to all the absolute coordinates and then draw into the window. The graphics context must have its plane mask set to the value of the overlay mask property (so as to avoid altering the overlay plane) and the foreground set to one of the numbers in the colour table array. If the drawing operation results in anything being drawn with the background colour then the background should also be set to one of the numbers in the colour table array, usually the first.

If the drawing operation involves a large amount of data it may be more efficient to only draw into the pixmap and then copy the pixmap to the window with XCopyArea. The destination position should be the x and y offset values and again, the overlay plane must be protected by the plane mask in the gc.

7.3 Drawing in the Overlay Plane

Drawing in the overlay plane is just the same as drawing into the window except that the plane mask must be set to the complement of the overlay mask property and the foreground and background colours must be all 1s and all 0s respectively1. The overlay offset values must be added to the coordinates when drawing into the window.

7.4 The Colour Table

On a display with a writeable colour table, the colour table property is a list of the colour cells allocated to the refresh process and must not be altered.

On a display with a fixed colour table the colour table property will list all possible pixel values—since the colour cells can’t be changed they can be used by all windows—and the colour table can be used to map “virtual” pixel values to the real pixel values used to write to the window and may be altered. For example, GKS uses the colour table to map colour indices onto pixel values.

If a window has an overlay plane, the colour of the overlay plane is set by setting the colour cells that correspond to values listed in the colour tables ORed with the bit position of the overlay plane (ie. the complement of the plane mask).

7.5 Scrolling

Scrolling of the window and overlay planes is achieved by setting the values of the offset and overlay offset properties. The refresh process is notified of the changes and updates the destination positions it uses when copying the pixmap. However, it does not update the window when the property values change so the application that changes the offsets must copy the window contents to the new position itself.

7.6 Examples

Some example programs that illustrate how to perform various operations on a GWM window can be found in the gwm examples directory ($STARLINK_DIR/share/gwm on Starlink systems).

7.7 Subroutine Specifications

1Of course in actual fact only the bit that corresponds to the overlay plane matters since the rest are masked by the plane mask but all 1s and all 0s is the easiest value to use