2    Components and Concepts

Even for WS programmers who are familiar with the PostScript language, the Display PostScript system for WS introduces new concepts. For instance, some familiar terms such as "client," "context," and "state" take on new meanings.

This chapter summarizes components and concepts of the Display PostScript system. Some of these topics are system-independent; others are system-specific. In this manual, the term system-independent refers to components and concepts found in all implementations of the Display PostScript system. System-specific refers to components found in only some implementations of the Display PostScript system and whose exact names and capabilities vary among implementations.

The Display PostScript system for WS is the systembeing described in this manual, so WS-specific and system-specific mean the same thing here. Note that some WS-specific components are also X-specific: they exist only in X-based implementations of the Display PostScript system.

This chapter emphasizes mainly WS-specific concepts and components.

2.1    Components

The Display PostScript system consists of three main components:

• PostScript interpreter

• Client Library

• The pswrap translation program

In WS, the PostScript interpreter resides on the X server; the Client Library is linked with the X client. The client and server can reside on the same workstation or on different workstations connected by a network.

2.1.1    PostScript Interpreter

In WS, the PostScript interpreter is an X server extension that executes PostScript language code sent from applications. The interpreter implements the full PostScript language, including operators for color and display. You can imagine the PostScript interpreter as a PostScript printer. Unlike a printer, however, the interpreter can concurrently execute several jobs.

2.1.2    Client Library

The Client Library is the set of C language routines through which applications communicate with the PostScript interpreter. The Client Library routines communicate with the PostScript interpreter by calling Xlib routines and low-level Display PostScript system routines implemented as extensions to Xlib. Note that, although there is currently no toolkit interface to Display PostScript system itself, applications that use the system can use toolkit interfaces to X as usual.

Note

Except where noted, the term application means a WS application program that uses the Display PostScript system.

The Client Library routines and data structures that make up the application programming interface to the Display PostScript system are defined in six header files. Only one of these six files is X-specific: dpsXclient.h. (For more information about dpsXclient.h, see Chapter 5.)

2.1.3    The Translation Program: pswrap

The pswrap translator is a program that converts procedures written in the PostScript language into routines that can be called from applications written in C. The converted routines are called wrapped procedures, or wraps. In WS, pswrap is installed in the directory /usr/bin.

A special set of ready-to-call wraps is included in the Client Library; most of these wraps send a single PostScript operator. These single-operator wrapped procedures are called singleops. (For more information on singleops, see Chapter 5.

2.2    Concepts

Before you can write an application that uses the Display PostScript system, you should understand a few essential concepts. The following section introduces those concepts.

2.2.1    Contexts

The term context is familiar to X programmers. In the Display PostScript system, however, a context is not an X Graphic Context (GC). Instead, a context is a destination to which an application sends PostScript language code. A PostScript context is either an execution context or a text context. Except where noted otherwise, the term context refers to a PostScript context; the X Graphic Context is referred to as the GC or as the X Graphic Context. Also, except where noted, the term context includes both execution contexts and text contexts.

2.2.1.1    Execution Context

An execution context is a destination that executes PostScript language code sent from an application. In WS, that destination is the PostScript interpreter of the X server. Just as the interpreter is like a PostScript printer, an execution context is like a print job.

In WS, a PostScript execution context is usually associated with an X display, an X drawable, and a GC. The PostScript execution context uses only the following fields of the GC:

clip_mask
clip_x_origin
clip_y_origin
plane_mask
subwindow_mode

The Display PostScript system in WS treats the X drawable and GC as part of the PostScript graphics state, a data structure that defines how PostScript operators execute.

2.2.1.2    Text Context

A text context is a destination that does not execute the PostScript language input it receives from an application. For example, the destination might be a text file or a WS stream, such as stdout. The destination is specified in the text-handling routine that the application assigns when creating the text context.

Sending PostScript language input to a text context provides a way to get a printable copy of input that would otherwise be sent to an execution context. This capability is particularly useful in debugging applications.

Note

In this manual, except where noted otherwise, the term input means input to a context on the server, not to an application on the client. Conversely, output means output from a context.

2.2.2    Context Record and DPSContext Handle

All contexts reside on the server. However, on the client, each context is represented by a context record, whose data type is DPSContextRec. The DPSContextRec stores the attributes of the context, for instance, the pointer to its error-handling routine.

Applications do not access the DPSContextRec directly. Instead, when calling Client Library routines, applications explicitly or implicitly pass a pointer to the DPSContextRec. This pointer, or handle, is of type DPSContext and is known as the DPSContext handle.

2.2.3    Context Status

An execution context can be in any of several states. For example, a context might be ready to execute, or it might be waiting for PostScript language code from the application. An application can monitor the execution state of a context by requesting context status events from the server. A context status event is an X event whose integer value represents the execution state of the context: its context status. Each time the context status changes, the server generates a context status event.

Although the server generates context status events, it does not automatically send them. To receive context status events, an application must explicitly set the context status mask, a data structure associated with each execution context. (For more information about the context status mask, see the description of the Client Library routine XDPSSetStatusMask in Chapter 5.)

2.2.4    Current Context

A typical application creates only one context. For this reason, the Display PostScript system lets an application specify one context as the current context. The current context is the default context for Client Library routines that take an implicit context argument.

2.2.5    Space

On the server, each execution context has virtual memory (VM) known as a space. In addition to the space of each execution context, there is shared VM, which is shared among all execution contexts of a server.

If an application creates multiple contexts, it can make them share a single space, thereby simplifying communication among them.

2.2.6    Identifiers

In WS, execution contexts and spaces are associated with X resources on the server. For this reason, execution contexts and spaces have, in addition to their PostScript language ID, an X resource ID (XID). Application programmers, however, seldom need to reference these XIDs.

2.2.7    Coordinate Systems

The Display PostScript system and X both use a coordinate system for imaging, but the coordinate system used by the Display PostScript system differs from that used by X. This section briefly explains both coordinate systems and explains how they interact in WS.

Each X window has a coordinate system whose origin is always the upper left corner. From this X origin, x increases from left to right; y increases from top to bottom, as shown in Figure 2-1.

Figure 2-1: X Coordinate System

The origin used by the Display PostScript system is called the user space origin. Unlike the X origin, the user space origin can be specified.

From the initial user space origin, x increases from left to right (as in X), but y increases from bottom to top, as shown in Figure 2-2.

Figure 2-2: User Space Coordinate System Used by the PostScript Language

In WS, the initial user space origin is offset from the X origin. That is, applications specify the initial user space origin as a point in the X coordinate system, as shown in Figure 2-3.

In this figure, an application has created a window measuring 300 x 300 pixels. The application has specified the X coordinates [0,300] (the window's lower left corner) as the initial user space origin. Thus, the window's lower left corner becomes the origin [0,0] of the user space coordinate system.

Figure 2-3: Initial User Space Origin Offset from X Origin

When an X window is resized, its user space origin moves according to the bit gravity of the window. (For more information on how resizing a window affects its user space origin, see Section 4.5.)