mgv 3.1.5: A Motif PostScript Viewer: The Interface to Ghostscript

30. The Interface to Ghostscript

30.1 The GHOSTVIEW Environment Variable

When the GHOSTVIEW environment variable is set, ghostscript draws on an existing drawable rather than creating its own window; ghostscript will draw in either a window or a pixmap depending on the contents of this variable.

The general form of the GHOSTVIEW variable is

        window-id [pixmap-id]

where window-id is the identifier of the destination window (XtWindow(ghostview_widget) for example) and the optional pixmap-id value is the identifier for a pixmap to draw into; both values are of type XID (32-bit unsigned integer). If only a window is specified, ghostscript will draw into that window but if the pixmap is also specified, all drawing will be done on the pixmap. In both cases the window is used to determine the colormap, screen, and visual to use; if the destination is a window, then the height and width will be retrieved from the window, otherwise, the dimensions will be those of the pixmap. All remaining information is retrieved from the GHOSTVIEW property on the window (when drawing is done to a pixmap, this property is deleted when read). Any events that ghostscript wishes to send will be directed at the window specified in the GHOSTVIEW environment variable.

30.2 The GHOSTVIEW Property

The GHOSTVIEW property is of type STRING and should have the form

        bpixmap orient llx lly urx ury xdpi ydpi [left bottom top right]

and a scanf(3) format of

        %d %d %d %d %d %d %f %f %d %d %d %d

The parameters are:

bpixmap

Pixmap id of the backing pixmap for the window. If no pixmap is to be used, this parameter should be zero and this parameter must be zero when the destination is a pixmap rather than a window.

orient

This should be a number representing the page orientation. The value is the clockwise rotation of the paper in degrees; only 0, 90, 180, and 270 are permitted

llx, lly, urx, ury

The bounding box of the drawable in PostScript points in the default user coordinate system.

xdpi, ydpi

These values specify the horizontal and vertical resolution of the destination. Even though these values may be computed from other parameters, they are specified to avoid round-off errors.

left, bottom, top, right

These optional parameters specify the margins around the window in PostScript points; the margins extend the imageable area beyond the boundaries of the window. This is primarily used for popup zoom windows. Some PostScript programs position themselves based on the imageable area so these values are useful at times. Any unspecified margins are assumed to be zero.

30.3 Events from Ghostscript

If the final destination is a pixmap, the client will get a property notify event when ghostscript reads the GHOSTVIEW property causing it to be deleted.

Ghostscript sends events to the window where it read the GHOSTVIEW property; these events are of type ClientMessage and the message_type is set to either PAGE or DONE. The first long data value specifies the window which is to be used when sending replies to ghostscript; the second long data value specifies the primary drawable which is:

the pixmap if ghostscript is drawing into a pixmap which was specified in the GHOSTVIEW environment variable
the destination window if the window does not have a backing pixmap
the backing pixmap of the destination window if it has one.

This field is necessary to distinguish multiple ghostscripts rendering to separate pixmaps when the GHOSTVIEW property was placed on the same window. The PAGE message indicates that a page has been completed; ghostscript will wait until it receives a ClientMessage whose message_type is NEXT before continuing. The DONE message indicates that ghostscript has finished processing.