Digital PDFs

AA-PAJUA-TE

May 1989

75 pages

Original

2.8MB

Document:	ULTRIX Worksystem Software Guide to Developing Applications for the Display PostScript® System
Order Number:	AA-PAJUA-TE
Revision:	000
Pages:	75
Original Filename:

OCR Text

VL TRIX W orksystem Software

Guide to Developing Applications for the
Display PostScript® System

Order Number: AA - PAJUA- TE

ULTRIX Worksystem Software

Guide to Developing Applications for the
Display PostScript® System

Order Number: AA-PAJUA-TE

Product Version:
Operating System and Version:

ULTRIX Worksystem Software, Version 2.2
ULTRIX Operating System, Version 3.0 or higher

This manual introduces the Display PostScript® system extension of the ULTRIX Worksystem
Software and describes how to develop applications that use this extension.

digital equipment corporation
maynard, massachusetts

Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in
subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software clause of DFARS 252.227-7013.

The infonnation in this document is subject to change without notice and should not be construed as a commitment
by Digital Equipment Corporation. Digital Equipment Corporation assumes no responsibility for any errors that may
appear in this document.
The software described in this documen~ is furnished under a license and may be used or copied only in accordance
with the tenns of such license.
No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Digital or its
affiliated companies.

The following are trademarks of Digital Equipment Corporation:
CDA
DEC
DECUS
DECnet
DECstation
DECwindows
DDIF
DDIS

DTIP
MASSBUS
MicroVAX
Q-bus
ULTRIX
ULTRIX Mail Connection
ULTRIX Worksystem Software

VAX

VAXstation
VMS
VMS/ULTRIX Connection
VT
XUI

mDmDamO

PostScript and Display PostScript are registered trademarks of Adobe Systems, Inc.
UNIX is a registered trademark of AT&T in the USA and other countries.
X Window System, X, and XII are registered trademarks of MIT.
This manual was written and produced by the Open Software Publications group.

Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 1

vii

Introduction to the Display PostScript System

1.1

What Is the Display PostScript System? .......................... .

1-1

1.2

PostScript Language Imaging Capabilities ......................... .

1-1

1.3

Display PostScript System in UWS .............................. .

1-2

1.4

Summary of Documentation ................................... .

1-2

Chapter 2
2.1

2.2

Chapter 3

Components and Concepts
2-1
2-1
2-2

Components .............................................. .
2.1.1
PostScript Interpreter ................................. .
Client Library ....................................... .
2.1.2
2.1.3
The Translation Program: pswrap ......................... .

2-2

Concepts ................................................. .
2.2.1
Contexts .......................................... .
2.2.1.1
Execution Context ........................... .
Text Context ............................... .
2.2.1.2
2.2.2
Context Record and DPSContext Handle .................... .
Context Status. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.3
2.2.4
Current Context ..................................... .
2.2.5
Space ........................................... .
2.2.6
Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.7
Coodinate Systems .................................. .

2-2
2-3
2-3
2-3
2-4
2-4
2-4
2-4
2-4

2-2

Getting Started

3.1

Developing a Typical Application ................................ .

3-1

3.2

Basic Application Requirements ................................ .

3-3

3.3

Sample Application: examplemain ............................... .
3.3.1
What the Sample Application Does ........................ .
3.3.2
The Main Code ..................................... .
3.3.3
Source File for Wrap ................................. .
3.3.4
Running examplemain ................................ .

3-4
3-5

3-6
3-8
3-9

iii

3.4

Building XDPS Applications ................................... .
3.4.1
Including Header Files ................................ .
3.4.2
Compiling ......................................... .
3.4.3
Linking ........................................... .
3.4.4
Invoking pswrap from a Makefile ......................... .
3.4.5
A Sample Makefile ................................... .

3-9
3-9
3-10
3-10
3-10
3-11

3.5

More Sample Applications .................................... .
3.5.1
Examples Contrasting Design Approaches . . . . . . . . . . . . . . . . . . . .
3.5.2
Running the Sample Applications ......................... .

3-12
3-12
3-13

3.6

Summary of Basic Tasks ..................................... .

3-13

Chapter 4
4.1

PostScript Language Encoding ................................. .

4-1

4.2

Buffering and the Client Library ................................ .

4-1

4.3

Accessing Files on the Server .................................. .

4-2

4.4

Converting Coordinates ...................................... .
4.4.1
Preparing to Convert Coordinates ......................... .
4.4.2
X Coordinates to User Space Coordinates ................... .
4.4.3
User Space Coordinates to X Coordinates ................... .

4-2
4-2
4-3
4-3

4.5

Resizing Windows .......................................... .
4.5.1
Window Resizing and the Clipping Path ..................... .
4.5.2
Window Resizing and the User Space Origin ................. .

4-3

4.6

Synchronizing the Display PostScript System and X .................. .

4-6

4.7

Synchronizing Client and Context ............................... .

4-7

4.8

Sharing Contexts and Spaces .................................. .

4-7

4.9

Using Color ............................................... .
4.9.1
Converting Colors and Shades into Pixel Values ............... .
4.9.2
Defining a Color Cube and Gray Ramp ..................... .
4.9.2.1
Using the Color Cube ......................... .
Using the Gray Ramp ......................... .
4.9.2.2
4.9.3
Rendering Colors Not in the Color Cube .................... .
4.9.4
The colorinfo Array and XStandardColormap Structures .......... .

4-7
4-7
4-8
4-9
4-9
4-10
4-10

Chapter 5

Advanced Concepts and Tasks

4-4
4-4

Client Library Routines for UWS

5.1

System-Specific Header File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-1

5.2

X-Specific Singleops ......................................... .

5-2

5.3

Naming Conventions ........................................ .

5-3

5.4

Format of Routine Descriptions ................................. .

5-4

5.5

Client Library Routine Descriptions .............................. .

5-4

Chapter 6

X-Specific Operators for UWS

6.1

About the Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6-1

6.2

Operator Errors ............................................ .

6-2

6.3

Operator Descriptions ........................................ .

6-3

Sample Application: examplemain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-6
3-9
3-11
4-3
5-2

Index

Examples
3-1
3-2
3-3
4-1
5-1

Source File for Wrap Called by examplemain . . . . . . . . . . . . . . . . . . . . . . . . . .
Makefile for examplemain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Wrap Returning CTM, Its Inverse, and Current User Space Origin ........... .
Definitions of X-specific Singleops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Figures
1-1
2-1
2-2
2-3
3-1
3-2
3-3

Display PostScript System as Implemented in UWS . . . . . . . . . . . . . . . . . . . . .
X Coordinate System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User Space Coordinate System Used by the PostScript Language ........... .
Initial User Space Origin Is Offset from X Origin . . . . . . . . . . . . . . . . . . . . . . . .
Developing a Typical Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Output of the examplemain Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Output of the Sample Calculator Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4-1

Resizing Window Whose Bit Gravity Is NorthWest . . . . . . . . . . . . . . . . . . . . . . .

4-2

Resizing Window Whose Bit Gravity Is SouthWest . . . . . . . . . . . . . . . . . . . . . .

1-2
2-5
2-6
2-7
3-2
3-5
3-12
4-5
4-6

Tables
1-1
3-1
3-2
4-1
4-2
4-3
5-1
5-2

Summary of Display PostScript Documentation . . . . . . . . . . . . . . . . . . . . . . . . .
Online Sample Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Summary of Basic Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Default PostScript Language Encodings for XDPS. . . . . . . . . . . . . . . . . . . . . . .
Mapping Between colorinfo Array and XStandardColormap Storing Color Cube ...
Mapping Between colorinfo Array and XStandardColormap Storing Gray Ramp . . .
Arguments Used by X-Specific Singleops . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Naming Conventions in the Client Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6-1

Operands and Results for X-Specific Operators . . . . . . . . . . . . . . . . . . . . . . . .

6-2

Errors for X-Specific Operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-3
3-12
3-13
4-1
4-10
4-11
5-3
5-3
6-2
6-2

Preface
This manual introduces the Display PostScript® system extension of Digital's
ULTRIX Work system Software (UWS). The manual describes mainly UWSspecific concepts, tasks, and facts that programmers must know to write Display
PostScript applications for UWS.
This manual supplements Display PostScript system documentation written
by Adobe Systems, Inc. This Adobe documentation is included in the UWS
documentation set and describes the system-independent aspects of the Display
PostScript system.

Audience
The Guide to Developing Applications for the Display PostScript System is intended for experienced UWS application programmers who are familiar with C
language programming. The Guide assumes that the reader is familiar with the
PostScript language. In addition, the Guide assumes that the reader has access
to Display PostScript system documentation from Adobe Systems, Inc., which is
part of the UWS documentation set

Organization
This manual consists of six chapters:
Chapter 1 introduces the Display PostScript system and lists the capabilities it
adds to UWS.
Chapter 2 describes the main components of the Display PostScript system and
summarizes key concepts.
Chapter 3 explains how to start writing applications for the Display PostScript
system and presents a simple example program.
Chapter 4 presents advanced concepts and tasks.
Chapter 5 describes the UWS-specific header file of the Display PostScript system
Client Library and describes each UWS-specific Client Library routine.
Chapter 6 describes X-specific operators provided by UWS.

vii

Related Documents
The following UWS manuals help you understand the portions of UWS that
interact with the Display PostScript system extension.

•

Guide to the Xlib Library: C Language Binding

•

Guide to VAX C

The X Window System: C Library and Protocol Reference, published by Digital
Press, explains the X Window System, which UWS implements.
The following manuals from Adobe Systems, Inc., are included in the UWS
documentation set; they describe system-independent aspects of the Display
PostScript system.

•

PostScript Language Perspective for Software Developers

•

Display PostScript System Client Library Reference Manual

•

PostScript Language Extensions for the Display PostScript System

•

PostScript Language Color Extensions

•

Display PostScript System pswrap Reference Manual

The following books, published by Addison-Wesley Publishing Company, Inc., help
you understand the PostScript language:

•

PostScript Language Reference Manual

•

PostScript Language Tutorial and Cookbook

•

PostScript Language Program Design

Conventions
The following typographical conventions are used in this manual:

Convention

this typeface
this typeface

viii

Meaning
In examples, a horizontal ellipsis means that additional parameters, values, or other information can be
entered, that preceding items can be repeated, or that
optional parameters have been omitted.
In text and examples, all directory names, file names,
and code samples appear in this typeface.
In text and examples, PostScript language operators
and X-specific operators appear in this typeface.

Chapter 1

Introduction to the Display PostScript System
To display or print graphics, an application must have an imaging model, a set
of rules for describing pictures and text. One of the most popular imaging models
is that of the PostScript page-description language, from Adobe Systems,
Inc. Originally developed for hardcopy output devices, such as laser printers, the
PostScript language imaging model has been adapted for bitmap displays through
Adobe's Display PostScript system.
Digital's ULTRIX Worksystem Software (UWS) implements the imaging
models of the X Window System and the Display PostScript system. UWS
applications can mix X and PostScript language imaging calls, even within a
single window, using a single network connection to an X server. This manual
introduces the Display PostScript system and shows how to develop UWS
applications that use it.

1.1

What Is the Display PostScript System?
The Display PostScript system is software that extends the PostScript imaging
model to bitmap display systems. With the Display PostScript system, you can
design and write applications in a gener2J-purpose language like C, yet describe
their images and text using the device-independent PostScript imaging model.

1.2 PostScript Language Imaging Capabilities
You are probably familiar with the capabilities of X imaging. The following
capabilities are found in PostScript language imaging but not in X imaging:
•

Coordinate system that can be moved, rotated, and scaled

•

Bezier curves

•

Device-independent color model with dithered (approximated) colors

•

Text that can be scaled and rotated

•

Image operators for scanned images
(scaling, rotating, transformations, gray-scale manipulation)

Introduction to the Display PostScript System

1-1

1.3 Display PostScript System in UWS
The Display PostScript system is a system-independent client/server architecture
that can be implemented on a variety of windowing systems. In this architecture,
the server consists mainly of a PostScript interpreter, which executes PostScript
language code that displays images on a user's screen. The client is an
application that communicates with the server through a set of routines known
as the Client Library.
UWS implements the Display PostScript system as an extension to the X Window
System, on which UWS is based. The Display PostScript system server is an
extension to the X server; the Client Library is an extension to Xlib. The Display
PostScript system extension of UWS lets a C language application display images
in an X window by calling functions that send PostScript language code.
Figure 1-1 shows the UWS implementation of the Display PostScript system.
(For brevity, this manual often refers to this implementation as XDPS.) For
more information about how UWS implements the Display PostScript system, see
Chapter 2.
Figure 1-1: Display PostScript System as Implemented in UWS

X Drawable

: i
Client
X Client
Library
Application
r------ .,....
...
Written
X Protocol
inC
Xlib
with
Extension
for Display
PostScript
System

PostScript
Interpreter

X Server

Z8-0310-R

1.4 Summary of Documentation
To understand and use the Display PostScript system in UWS, you must be
familiar with these subjects:
•

The ULTRIX operating system

•

The C programming language

•

UWS programming

•

The PostScript language

1-2 Introduction to the Display PostScript System

•

The system-independent aspects of the Display PostScript system

•

The UWS-specific aspects of the Display PostScript system

This manual describes mainly the UWS-specific aspects of the Display PostScript
system. To learn about more general aspects, see the Display PostScript System
Client Library Reference Manual.
Table 1-1 briefly describes UWS manuals and other books that help you
understand the Display PostScript system in UWS.
Table 1-1:

Summary of Display PostScript Documentation

To learn about

Read this book

Where to find it

UWS-specific aspects of the Display
PostScript system

Guide to Developing Applications for
the Display PostScript System

System-independent introduction to
the Display PostScript system
System-independent reference for
the Display PostScript system
PostScript language

PostScript Language Perspective for
Software Developers
Display PostScript System Client
Library Reference Manual
PostScript Language Reference
Manual, PostScript Language
Tutorial and Cookbook, PostScript
Language Program Design
PostScript Language Extensions for
the Display PostScript System
PostScript Language Color
Extensions
Display PostScript System pswrap
Reference Manual
Guide to the Xlib Library: C
Language Binding, X Window
System: C Library and Protocol
Reference

UWS
documentation
set (docset)
UWS docset

PostScript language as extended for
the Display PostScript system
PostScript language as extended for
color support
Converting PostScript procedures
into C-callable routines
Xlib programming

UWS docset
Most technical
bookstores

UWS docset
UWS docset
UWS docset
UWS docset

Introduction to the Display PostScript System

1-3

Chapter 2

Components and Concepts
Even for UWS programmers who are familiar with the PostScript language, the
Display PostScript system for UWS 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 systemspecific. 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 UWS is the "system" being described in this
manual, so "UWS-specific" and "system-specific" mean the same thing here.
Note that some UWS-specific components are also ''X-specific'': they exist only in
X-based implementations of the Display PostScript system.
This chapter emphasizes mainly UWS-specific concepts and components. For a
more general introduction to the Display PostScript system, see the PostScript
Language Perspective for Software Developers and the Display PostScript System
Client Library Reference Manual.

2.1

Components
The Display PostScript system consists of three main components:
•

PostScript interpreter

•

Client Library

•

The pswrap translation program

In UWS, 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 UWS, 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.''

Components and Concepts 2-1

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 lowlevel 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 UWS 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 UWS,
pswrap is installed in the directory /usr /bin. For information on using
pswrap, see the Display PostScript System pswrap Reference Manual.
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
and the Display PostScript System Client Library Reference Manual.

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

2.2.1

Contexts
The term "context" is familiar to X programmers. But in the Display PostScript
system, a context is not an X Graphic Context, or "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.
NOTE

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 Components and Concepts

2.2.1.1

Execution Context

An execution context is a destination that executes PostScript language code sent
from an application. In UWS, 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 UWS, 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 UWS treats the X drawable and GC as part
of the PostScript graphics state, a data structure that defines how PostScript
operators execute. (For information about the PostScript graphics state, see the
PostScript Language Reference Manual.)
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 an ULTRIX 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.

Components and Concepts

2-3

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 UWS, 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

Coodinate 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 UWS.
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.

2-4 Components and Concepts

Figure 2-1:

X Coordinate System

y increasing

ZS-0314-R

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. (For more information
about user space, see the PostScript Language Reference Manual).

Components and Concepts

2-5

Figure 2-2:

User Space Coordinate System Used by the PostScript Language

y increasing

x increasing
[0,0]
Initial user space origin
ZS-031S-R

In UWS, 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.

2-6 Components and Concepts

Figure 2-3:

Initial User Space Origin Is Offset from X Origin

y increasing
300 pixels

ZS-0316-R

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.

Components and Concepts 2-7

Chapter 3

Getting Started
This chapter shows you how to develop a typical application that uses the
Display PostScript system. It describes the steps you follow to develop a typical
application and describes the steps that a typical application performs. The
chapter then presents a sample application.
Before You Start

Before reading this chapter, be sure you understand the following components
and concepts, covered in Chapter 2:
•

PostScript interpreter

•

Client Library

•

The pswrap translation program

•

PostScript context

If you understand these, you are ready to start.

3.1

Developing a Typical Application
To develop a typical application, you follow six main steps, as shown in
Figure 3-1. (Steps 3 through 5, however, take much less time than the others.)

o Design the application.
8 Write the main C-Ianguage module and any custom PostScript language
procedures that the application calls.

o Convert the custom PostScript language procedures into C-callable routines
by running the pswrap translation program.

o Compile the C-Ianguage code with:
•

The output files from pswrap

•

The X header files

•

The header file dpsXclient. h and any optional XDPS header files, like
dpsops.h

o Link the resulting object file with the X libraries and with the Client Library.
(3 Run and debug the executable application.

Getting Started

3-1

Figure 3-1:

o
e

Developing a Typical Application

DESIGN PHASE

examplewraps.psw

examplemain.c

e
examplemain.c

examplewraps.c

______X_lib____

examplewraps.h

Linker

dpsXclient.h

:}-1

dpsops.h

Xlib.h

Client Library

Executable
Application
Program
ZS-0313-R

Step 1: Design the Application

In UWS, Display PostScript system applications are written in C and send
PostScript language code to a context, usually an X server. But to design an
application, you must make several decisions. For example, you must decide:
•

Whether to code mostly in C or mostly in the PostScript language

•

Whether to create one PostScript context or several

•

Whether to send PostScript language code by custom wraps, by singleops, as
text, or by a combination of these methods

For a typical simple application, the following design decisions are usually best:
•

Code mostly in C; use the PostScript language for imaging-related tasks only.

•

Create only one PostScript context.

•

Send lengthy PostScript language segments as custom wraps; send single
PostScript language statements as singleops.

3-2 Getting Started

A complete discussion of application design is beyond the scope of this book. To
help you see and understand how design decisions affect XDPS applications, the
UWS distribution kit includes source files for several sample applications. For
more information about these sample applications, see Section 3.5.
Step 2: Write Your C Code and PostScript Language Code

Mter you have designed your application, you write the C-Ianguage code and the
PostScript language procedures that your application sends.
(It is also possible to write applications that read PostScript language code from

the user's keyboard or from a file. For a sample program of this type, see the
program DPStest. By default, the source files for DPStest are installed in the
directory / u s r / examp 1 e s / dp s / dp s t est. For instructions on running the
program, see Section 3.5.
Step 3: Convert Your PostScript Language Procedures

If you have written any PostScript language procedures for your application, you
should convert them to wraps, that is, to routines that can be called from your
C-Ianguage code. To CO:'lvert the PostScript language procedures, you process
them with the pswrap translation program.

For each PostScript language input file, pswrap can produce two output files:
a C-callable procedure and an associated header file. For information on using
pswrap, see the Display PostScript System pswrap Reference Manual.
Steps 4 and 5: Compile and Link

After you have converted your PostScript language procedures to C-callable
routines, you compile and link your source files. That is, you compile your main
C-Ianguage file with:
•

The output files from pswrap

•

The X header files

•

The dpsXclient. h header file and, optionally, other Client Library header
files

You link your application with the Client Library and with the X libraries. (For
instructions on compiling and linking XDPS applications, see Section 3.4.)
Step 6: Run and Debug Your Application

You are now ready to run and debug your application.

3.2 Basic Application Requirements
All applications send PostScript language statements to a context. Typically,
the context is an execution context-in XDPS, the PostScript interpreter of an X
server. Most XDPS applications perform three main steps:
1.

Initialization

2. Communication
3. Termination

Getting Started

3-3

Step 1: Initialization

Typically, to initialize an XDPS application, you perform three steps:
1.

Establish communication with an X server, create a window, and create a GC.

2. Create a PostScript execution context by calling an X-specific Client Library
routine such as XDPSCreateSimpleContext. (For more information on
creating contexts, see the descriptions of XDP SCreateSimpleContext and
XDPSCreateContext in Chapter 5.)
3. Perform any additional X-specific initialization, such as mapping the window.
Step 2: Communication

Mter initializing, most XDPS applications call custom wraps, singleops, or
other Client Library routines to send text and PostScript language statements to a context. For example, to send information to a context, an application might either call a custom wrap or call one of two Client Library
routines: DPSWri tePostScript (for PostScript language statements) or
DPSWri teData (for data).
To process text or errors from a context, the Client Library calls the text-handling
routine or error-handling routine that the application assigned when creating the context. The Client Library defines a default text-handling routine
(DPSDefaul tTextBackstop) and a default error-handling routine
(DPSDefaul tErrorProc ). Although these routines are called default routines,
to use them you must specify them explicitly when creating a context. For more
information on the default routines, see their descriptions in Chapter 5.
Step 3: Termination

Terminating a typical XDPS application is like terminating any other typical X
application. When you terminate an application, the X Window System destroys
the application's contexts, their spaces, and any other X resources belonging to
the application.

3.3 Sample Application: examplemain
This section presents examplemain, a simple program that shows the fundamentals of XDPS programming. The program uses the Display PostScript
system to paint a shaded square in a window of the user's screen, as shown in
Figure 3-2.

3-4 Getting Started

Figure 3-2:

Output of the examplemain Program

m No name

[!;]~

The examplemain program uses the Xlib interface to X, calls a custom wrap
to pick the shade of gray for painting, and calls a Client Library single-operator
procedure to do the actual painting.
There is more than one way to program almost any XDPS application. To see a
different approach to essentially the same sample application presented in this
section, see the section "Example Application Program" in the Display PostScript
System Client Library Reference Manual.

3.3.1

What the Sample Application Does
The sample application examplemain performs the following operations:
1. Connects the client to an X server with XOpenDisplay
2. Creates a window with XCreateSimpleWindow
3. Selects X event types Expose and ButtonPress with XSelectInput

Getting Started

3-5

4. Creates a Display PostScript execution context with
XDPSCreateSimpleContext, using the default text handler, the default
error handler, and the default GC
5. Displays the window with XMapWindow
6.

Chooses the shade of gray for painting, with a custom wrapped PostScript
language procedure named ChooseGray

7. Sets the shade of gray with DPSsetgray, a singleop from the Client Library
8. Paints a gray square with the singleop DPSrectfill each time an Expose
event is received and exits when a ButtonPress event is received
9. Destroys the context and space with DPSDestroySpace, and then closes
the display connection and exits
Unlike a more complete application, examplemain does not handle resizing of
the X window. (For information about window resizing in XDPS applications, see
Section 4.5.)

3.3.2

The Main Code
Example 3-1 is a complete listing of examplemain. c, the main C language file
of the sample application.

Example 3-1:

Sample Application: examplemain

* examplemain.c -- Simple X application that uses the Display PostScript
* system to draw a shaded square in a window, then exits when the user
* clicks the mouse.
*/
#include <stdio.h>
#include <Xlib.h>
#include <dpsXclient.h>
#include <dpsops.h>

/* Standard X Window C-language library */
/* X interface to DPS Client Library */
/* Declarations of singleops */

#include "examplewraps.h"

/* Interface to wrapped PostScript language code*/

(continued on next page)

3-6 Getting Started

Example 3-1 (Cont.):

Sample Application: examplemain

main ()
{

Display *dpy;
Window window;
DPSContext context;
float grayLevel;
XEvent event;
void TextOut();
void FatalError();

/* An X display */
/* A window of the X display */
/* A single PostScript context */
/* The shade of gray for the square */
/* An X event */
/* Forward declaration */
/* Forward declaration */

/*
* Open a connection to the X display specified in the argument
* to the XOpenDisplay routine.
The NULL argument causes
* XOpenDisplay to open a connection to the display specified
* by the DISPLAY variable of the user's environment.

*/
dpy = XOpenDisplay(NULL);
/*
* If unable to open the display, return an error message and
* exit immediately.

*/
if (dpy == NULL)
FatalError("Can't open display.\n");
/*
* Create a window on the X display. When mapped, the window will be
* 10 pixels from the left edge and 20 pixels from the upper edge.
* The window will be 800 pixels high by 800 pixels wide, with a
* black border 1 pixel wide and a white background.
*/
window = XCreateSimpleWindow(dpy, DefaultRootWindow(dpy),
10, 20, 800, 800, 1,
BlackPixel(dpy, DefaultScreen(dpy»,
WhitePixel(dpy, DefaultScreen(dpy»);
/*
* Select the X event types that the window accepts from
* the X server. The window accepts Expose events and
* ButtonPress events.

*/
XSelectInput(dpy, window, ExposureMask I ButtonPressMask);

/*
* Create a PostScript execution context to draw in the window.
* The origin of the context's coordinate grid is the point (0, 800)
* of the window.
The origin is therefore the bottom left corner
* of the window (the typical origin for a PostScript context) .

context = XDPSCreateSimpleContext(dpy, window,
DefaultGC(dpy, DefaultScreen(dpy»,
0, 800,
TextOut, DPSDefaultErrorProc, NULL);

/*
* If unable to create the context, return an error message
* and exit immediately.

*/
if (context == NULL)
FatalError("DPS refused to create a context.\n");
/*
* Map the window--that is, make it appear on the display.
The
* window will appear only after the window manager of the X server
* is free to process the mapping request. When the window appears,
* the context receives an Expose event as notification.

*/
XMapWindow(dpy, window);

/*
* Generate a random number that corresponds to the shade of gray
* (the graylevel) to be used when painting. To generate this number,
* call the ChooseGray routine, which is exported from the
* examplewraps.c file.
ChooseGray sends wrapped PostScript
* language code to the context, which then executes the code.
*/

(continued on next page)
Getting Started

3-7

Example 3-1 (Cont.):

Sample Application: examplemain

ChooseGray(context, &grayLevel);

/*
* Set the current gray level to the shade of gray chosen by
* ChooseGray. Setting the graylevel does not cause any painting;
* so you can set the graylevel even if the window
* has not yet appeared.
*/
DPSsetgray(context, grayLevel);

/*
* Wait for events from the X server; process each one received.
* For each Expose event, paint the same gray square in the same
* place on the display. To do this, call the DPSrectfill routine,
* a single-operator wrapped procedure declared in dpsops.h, a
* DPS Client Library header file.
The bottom left corner of
* the square is 100 points above the or~g~n and 100 points to
* the right of it. Each side of the square is 300 points.

* When a ButtonPress event is r.eceived, exit the event-processing loop.
*/
for (;;) {
XNextEvent(dpy, &event);
if (event.type == Expose)
DPSrectfill(context, 100.0, 100.0, 300.0, 300.0);
else if (event.type == ButtonPress) {
break;
}

/*
* Exit in an orderly manner. First, destroy the context by
* destroying its space (its memory). Next, destroy
* the window. Finally, close the connection to the X display.
*/
DPSDestroySpace(DPSSpaceFromContext(context»;
XDestroyWindow(dpy, window);
XCloseDisplay(dpy);

/*
* Output procedure for ordinary text messages from the context.
* Output is sent directly to standard error.

*/
void TextOut(context, buffer, count)
DPSContext context;
char *buffer;
unsigned count;
fwrite(buffer, 1, count, stderr);
fflush(stderr);

/*
* Error procedure. The application has encountered an error
* from which it cannot recover, so exit immediately.

*/
void FatalError(msg)
char *msg;
fprintf(stderr, msg);
exit(l);

3.3.3

Source File for Wrap
Example 3-2 is a complete listing of exarnplewraps . psw, the PostScript
language source file for the wrapped procedure called by the sample application
exarnplemain.

3-8

Getting Started

Processing examplewraps . psw with the pswrap translator produces two
output files: examplewraps. c and examplewraps . h. These output files
must then be compiled with examplemain. c.
Example 3-2:

Source File for Wrap Called by examplemain

/*
* examplewraps.psw -- source file for wrapped PostScript language procedure

* This is an example of PostScript language code to be converted to
* Client Library calls by pswrap.

* This PostScript language routine, ChooseGray, generates a random number that
* corresponds to the graylevel (shade of gray) to be used when the Display
* PostScript system paints. Note that the PostScript operator rand always
* generates the same sequence of random numbers.
So each time
* the program examplemain runs, ChooseGray chooses the same graylevel.

*/
defineps ChooseGray (DPSContext ctxl float *result)
rand
% Pick a random number between 0 and 2 A 31 - 1.
2 31 exp
% 2 A 31
div
% Random number between 0.0 and 1.0
result
% Return result.
endps

3.3.4

Running examplemain
By default, all the program-specific files needed to compile, link, and run
examplemain are installed in the /usr/examples/dps/gray-square
directory of your system. For instructions on compiling and linking, see
Section 3.4.

3.4 Building XDPS Applications
Mter you code an application, you build it by compiling and linking it. This
section describes how to build an application. It assumes that you are using
the ULTRIX make utility. (For more information, see make ( ) in the ULTRIX
Reference Pages.)
This section includes a complete makefile for the examplemain program
presented in Section 3.3.2.

3.4.1

Including Header Files
Before building an XDPS application, make sure that the main source module
includes the appropriate X header files and the UWS-specific Client Library
header file, dpsXclient . h.
The dpsXclient. h file is the only Client Library header file that all XDPS
applications must include. It, in turn, includes all other Client Library header
files, except psops . h, dpsops . h, and dpsexcept . h.
If your application calls singleops, you should also include psops. h or
dpsops. h, or both, depending on which defines the singleops that your
application calls. If your application uses the exception handling capability
of the Display PostScript system, you must also include dpsexcept . h. (Not to
be confused with error handling, exception handling is an advanced capability

Getting Started

3-9

that few applications require. For more information, see the Display PostScript
System Client Library Reference Manual.)

3.4.2

Compiling
You compile the main C-Ianguage module of your XDPS application with:
•

The X header files-for example, Xl ib . h

•

The dpsXclient. h header file

•

The psops . hand dpsops . h header files (if application calls singleops)

•

The output files from pswrap (if application calls custom wraps)

The Display PostScript system header files (among them, dpsXclient. h,
psops. h, and dpsops. h) are installed in the directory /usr/include/DPS.
To automatically include these files at compilation, add the following statement to
your makefile:
CFLAGS

= -I/usr/include/DPS

The option -I/usr/include/DPS causes the ULTRIX C compiler to search for
include files in /usr / inc 1 ude/DPS.

3.4.3

Linking
You link your XDPS application with the following libraries, in the order listed:

3.4.4

Library

Linker option

Client Library
Xlib extensions for Display PostScript system
DECwindows toolkit library
Xlib library
ULTRIX math library

-ldps
-lXext
-ldwt
-lXll
-1m

Invoking pswrap from a Makefile
Your makefile can automatically convert PostScript language procedures to
C-callable routines by running the pswrap translation program. For example, if
the PostScript language procedures have filenames ending in . psw, the following
make statements convert the procedures automatically:
. SUFFIXES: $ (.SUFFIXES) .psw .h
.psw. 0: $* .psw
$ {PSWRAP} -0 $*.c $*.psw
$(CC) $ (CFLAGS) -c $*.c
rm $*.c
.psw.h: $*.psw
${PSWRAP} -h $*.h $*.psw > /dev/null

3-10

Getting Started

3.4.5

A Sample Makefile
Example 3-3 shows a complete Makefile that builds the examplemain program
presented earlier in this chapter.

Example 3-3:

Makefile for examplemain

# @(#)Makefile 1.5 ULTRIX 9/2/88
DESTDIR=
EXAMPLETOPDIR=${DESTDIR}/usr/examples/dps
EXAMPLESUBDIR=${EXAMPLETOPDIR}/gray-square
INSTALLLIST = Makefile examplemain.c *.psw
OBJS = examplemain.o examplewraps.o
PSWRAP= ${DESTDIR}/usr/bin/pswrap
. SUFFIXES: $ (.SUFFIXES) .psw .h
.psw.o: $*.psw
$ {PSWRAP} -0 $*.c $*.psw
$(CC) $ (CFLAGS) -c $*.c
rm $*.c
.psw.h: $*.psw
$ {PSWRAP} -h $*.h $*.psw > /dev/null
. SUFFIXES:

.uil .uid

CFLAGS = -g -I${DESTDIR}/usr/include/Xll -I${DESTDIR}/usr/include/DPS \
-I${DESTDIR}/usr/include -I.
LIBS = ${DESTDIR}/usr/lib/libdps.a \
${DESTDIR}/usr/lib/libXext.a \
${DESTDIR}/usr/lib/libdwt.a \
${DDIFROOT}/usr/lib/libddif.a \
${DESTDIR}/usr/lib/libXll.a \
-1m

all: examplemain
examplemain: $ (OBJS)
$(CC) -0 examplemain $ (OBJS) $(LIBS)
examplemain.o: examplemain.c examplewraps.h
clean:
rm -f *.0 examplemain examplewraps. [ch] \#*

core

clobber: clean
-rm - f *
relink: :
rm -f examplemain
relink:: all

Getting Started

3-11

3.5 More Sample Applications
In addition to exampl emain, the UWS software includes source listings of
several other sample XDPS applications.

3.5.1

Examples Contrasting Design Approaches
UWS includes source listings and makefiles for four related sample programs:
calcO, calcl, calc2, and calc3. Each of these sample programs is an
implementation of the same application: a desktop calculator. Although all four
programs present a similar user interface (shown in Figure 3-3), the source code
of each program shows a different approach to XDPS application design.
Figure 3-3: Output of the Sample Calculator Programs

I!;BI@J

11;]1 calcO

elr

,
0

For the location of the sample calculator programs, see Table 3-1, which lists and
describes the sample Display PostScript system applications included in UWS.
Table 3-1: Online Sample Programs
Program Name
Description
calcO
calcl

calc2
calc3

DPStest

Calculator coded mainly in C, with
one window and one context
Calculator coded mainly in the
PostScript language, with one
window and one context
Calculator coded mainly in C, with
multiple windows and one context
Calculator coded mainly in C,
with multiple windows, multiple
contexts, and intercontext
communication
Executes PostScript language
statements entered from the
keyboard

Where to find it
/usr/examples/dps/calcO
/usr/examples/dps/calcl

/usr/examples/dps/calc2
/usr/examples/dps/calc3

/usr/examples/dps/dpstest

(continued on next page)

3-12 Getting Started

Table 3-1 (Cont.):
Program Name

Online Sample Programs
Description

examplemain

Displays a gray square generated
from a custom wrap and a singleop
An implementation of xclock that
uses the Display PostScript system
A graphic editor that paints
PostScript language images; a
complex sample application
Displays fireworks generated from
custom wraps

psclock
psdraw

pyr~

3.5.2

Where to find it
/usr / examples / dps / gray-square
/usr/examples/dps/psclock
/usr/examples/dps/psdraw

/usr / examples/ dps/pyro

Running the Sample Applications
To run one of the sample applications, you must first build it by following these
steps:
1.

Log on to your system and find the subdirectory storing the sample
application.

Copy the entire contents of that subdirectory to a subdirectory in your
account. (Note that the sample programs cal cO, calcl, calc2, and
cal c 3 must be copied to sibling directories, that is, to subdirectories at the
same level of the file system.)

Set your working directory to the subdirectory that received the copies in Step

2.
4.

Invoke the ULTRIX make utility by entering the command make at the
system prompt. (The make utility compiles and links the program. Note that
for the sample application psdraw, you must enter make install instead
of make. For information, see make ( ) in the ULTRIX Reference Pages.)

You can then run the program by entering its name at the system prompt. For
more information on building XDPS applications, see Section 3.4.

3.6 Summary of Basic Tasks
Table 3-2 lists common XDPS programming tasks and shows the operators and
Client Library routines for performing each task.
Table 3-2: Summary of Basic Tasks
To do this task..•

Create an execution context
Create a text context
Use the default text handler
Use the default error handler

Use these routines and operators
XDPSCreateSimpleContext or
XDPSCreateContext
XDPSCreateTextContext
DPSDefaultTextBackstop
DPSDefaultErrorBackstop

(continued on next page)

Getting Started

3-13

Table 3-2 (Cont.): Summary of Basic Tasks
To do this task...
Use these routines and operators

Find the space of a context
Find the default user space origin
Set the default user space origin
Find the GC of a context
Set the GC of a context
Restart a context
Find the current drawable
Set the current drawable
Convert between PostScript language IDs
and XIDs

Destroy a space
Destroy a context

DPSSpaceFromContext
currentXoffset 1
setXoffset
currentXgcdrawable
setXgcdrawable
DPSResetContext
currentXgcdrawable
setXgcdrawable
XDPSXIDFromContext
XDPSXIDFromSpace
XDPSContextFrornXID
XDPSSpaceFrornXID
DPSDestroySpace
DPSDestroyContext

1 Items in bold type are operators; all others are Client Library routines.

3-14

Getting Started

Chapter 4

Advanced Concepts and Tasks

In Chapters 2 and 3 you learned the basic concepts and tasks you need to write
simple applications using XDPS. But to write more complex applications, you
need the additional concepts and tasks described in this chapter.

4.1

PostScript Language Encoding
In XDPS, PostScript language code can be sent to a context in three encodings:
as a binary object sequence, as binary-encoded tokens, or as ASCII text. Each
PostScript context has two encoding parameters: DP SP rogramEncoding
and DPSNameEncoding. For an explanation and description of encoding and
encoding parameters, see the PostScript Language Extensions for the Display
PostScript System and the Display PostScript System Client Library Reference
Manual.
XDPS uses default values for the encoding parameters, so application
programmers can usually ignore encoding. Table 4-1 shows the default values for
the encoding parameters.

Table 4-1:

Default PostScript Language Encodings for XDPS
Context type
Encoding Parameter
Default Value

execution
execution
text
text

DPSProgramEncoding
DPSNameEncoding
DPSProgramEncoding
DPSNameEncoding

Binary object sequence (dps_binObjSeq)
User name index (dps _indexed)
ASCII characters (dps_ascii)
User name string (dps_string)

XDPS lets you change the encoding parameters of a context to any of the three
possible encodings. To change the encoding parameters, use the Client Library
routine DP SChangeEncoding, described in Chapter 5.

4.2 Buffering and the Client Library
In most implementations of the Display PostScript system, the Client Library
buffers its communications with the Display PostScript server. But in XDPS, the
Client Library communicates with the server by way of Xlib, which buffers its
own communication. To avoid duplicate buffering, the XDPS Client Library
performs no internal buffering. Instead, all buffering of Client Library
communication occurs in Xlib. As a result, the XDPS Client Library routine
DPSFlushContext performs the same tasks as the Xlib procedure XFlush.

Advanced Concepts and Tasks

4-1

4.3 Accessing Files on the Server
To preserve security on servers, XDPS lets applications access only certain files
stored on the server. Specifically, XDPS lets applications access only files stored
in two directories, referred to here as tempdir and permdir.
The tempdir directory is temporary: its contents are deleted each time the XDPS
server is started or reset, such as when the user logs out. In contrast, permdir
is a permanent directory: resetting and restarting do not affect its contents.
Applications can both read from tempdir and write to it. Applications can only
read from permdir; they cannot write to it.
To specify a file stored in tempdir, an application must prefix the filename with
%ternp%. To specify a file inpermdir, an application must use the prefix %perrn%.
If a filename is preceded by neither %ternp% nor %perrn%, XDPS searches for the
file first in tempdir and then in permdir. XDPS does not let applications access
files whose names include a slash (/), a bracket ([), or a colon(:).
By default, tempdir is the directory /usr/lib/DPS/ternpdir; permdir is
/usr/lib/DPS/perrndir. You can, however, assign other directory names.
To do so, specify those names in the XDPS server startup command. (For more
information, see the Release Notes and Installation Instructions.)

4.4 Converting Coordinates
The X Window System and the PostScript language use different coordinate
systems to specify points within the drawing area. As a result, XDPS applications
sometimes need to convert user space coordinates (used by the PostScript
language) into X coordinates, and vice versa. (For more information on user
space, see the PostScript Language Reference Manual.) This section explains how
to perform these coordinate conversions.

4.4.1

Preparing to Convert Coordinates
Before converting coordinates, an application should create a context, and then do
the following steps:

1. Perform any user space transformations.
2.

Get the current transformational matrix (CTM), its inverse, and the X
coordinates of the current user space origin.

Store these values in the VM associated with the context.

The application can then perform coordinate conversions for the context.
To get the CTM, its inverse, and the X coordinates of the current user space
origin, an application can call a custom wrap such as PSWGetTransforrn,
whose pswrap source file is shown in Example 4-1.

4-2 Advanced Concepts and Tasks

Example 4-1:

Wrap Returning CTM, Its Inverse, and Current User Space Origin

defineps PSWGetTransform(DPSContext ctxt I float ctm[6], invctm[6];
int *xOffset, *yOffset)
matrix currentmatrix dup ctm
matrix invertmatrix invctm
currentXoffset exch xOffset yOffset
endps
The following C language code calls PSWGetTransform:

DPSContext ctxt;
float ctm[6], invctm[6];
int xOffset, yOffset;
PSWGetTransform(ctxt, ctm, invctm, &xOffset, &yOffset);

4.4.2

X Coordinates to User Space Coordinates
To convert an X coordinate into a user space coordinate, an application can
execute the following C language code:

#define A COEFF 0
#define B COEFF 1
#define C COEFF 2
#define D COEFF 3
#define TX CONS 4
#define TY CONS 5
int x,y; /* X coordinate */
float ux, uy; /* user space coordinate */
x -= xOffset;
y -= yOffset;
ux
invctm[A_COEFF] * x + invctm[C_COEFF] * y + invctm[TX_CONS];
uy = invctm[B_COEFF] * x + invctm[D_COEFF] * y + invctm[TY_CONS];

4.4.3

User Space Coordinates to X Coordinates
To convert a user space coordinate into an X coordinate, an application can
execute the following C language code:

x
y

= ctm[A_COEFF] * ux + ctm[C_COEFF] * uy + ctm[TX_CONS] + xOffset;
ctm[B_COEFF] * ux + ctm[D_COEFF] * uy + ctm[TY_CONS] + yOffset;

4.5 Resizing Windows
An application or user can resize the window in which XDPS paints. Resizing
can affect two PostScript language settings, the clipping path and the user space
origin, as described in the following sections.

Advanced Concepts and Tasks

4-3

4.5.1

Window Resizing and the Clipping Path
PostScript language painting occurs only within the area known as the clipping
path. When initializing a context, XDPS sets the clipping path equal to the
size of the window. If the window is resized, however, XDPS does not reset the
clipping path. Instead, each time the window is resized, the application should
execute the PostScript language operator ini tclip, which reinitializes the
clipping path to match the window's new size. The application can then reexecute
any code that performs further clipping.

4.5.2

Window Resizing and the User Space Origin
When an application resizes the window of a context, the user space origin moves
according to the hit gravity of the window. Bit gravity is an X window attribute
that governs how partial window contents are preserved when a window is
resized. (Bit gravity is not to be confused with T:vindow gravity, an X attribute
that does not affect the user space origin.) In X, specifying the bit gravity of
a window is optional: the default value is ForgetGravi ty. XDPS treats
ForgetGravi ty as NorthWest gravity.
Because a window's user space origin moves according to the window's bit
gravity, resizing does not change the distance between the user space origin
and any PostScript language images already displayed. Because this distance is
unchanged, future PostScript language images align with those already displayed.
Compare Figures 4-1 and 4-2. The left side of Figure 4-1 shows a window
displaying the text "NorthWest". As shown, the user space origin is the window's
lower left corner, and the bit gravity is NorthWest.
The right side of the figure shows the same window after resizing. Notice that
the user space origin (and hence the displayed text) remains a constant distance
from the window's upper left corner: its "NorthWest" corner.

4-4 Advanced Concepts and Tasks

Figure 4-1:

Resizing Window Whose Bit Gravity Is NorthWest

NorthWest

Resize To

I
I
I
I

I
I
I

---- r;---

l~---

NorthWest

User space origin

ZS-0311-R

In Figure 4-2, the size of the window on the left and the position of its text are
the same as in Figure 4-1. Also the same is the user space origin: the lower left
corner. But in Figure 4-2, the hit gravity is SouthWest. Therefore, when the
window is resized, the user space origin and displayed text remain a constant
distance from the window's lower left corner: its "SouthWest" corner.

Advanced Concepts and Tasks

4-5

Figure 4-2:

Resizing Window Whose Bit Gravity Is SouthWest

SouthWest

Resize To .-(
I
I
I

I~---

!~ User space origin

SouthWest

I
I
I

--_. I

I~---

!~ User space origin
..
ZS-0312-R

The user space origin is typically the lower left corner of the drawing space. For
this reason, typical XDPS applications should explicitly set the bit gravity of their
windows to SouthWest.

4.6 Synchronizing the Display PostScript System and X
X imaging calls complete atomically. Therefore, XDPS applications need
not take special precautions when issuing X imaging calls before PostScript
language imaging calls. PostScript contexts, however, complete non-atomically
and asynchronously within the X server. Thus, when an application issues X
imaging calls immediately after issuing PostScript language calls, the X calls can
sometimes execute before the PostScript language calls. That is, it is possible for
X and the Display PostScript system to become unsynchronized.
Few applications need to synchronize the Display PostScript system and X
explicitly. But to do so, an application can call the Client Library routine
DPSWaitContext before issuing the X imaging calls that follow PostScript
language calls. DPSWaitContext forces the PostScript language calls to
complete before the X calls.
NOTE

DPSWaitContext causes a round trip to the server. Such trips
impair performance, so call DPSWaitContext only when needed.

For more information on DPSWaitContext, see the Display PostScript System
Client Library Reference Manual.

4-6 Advanced Concepts and Tasks

4.7 Synchronizing Client and Context
Applications, or clients, sometimes need to pause the execution of a context.
Pausing a context lets an application take control when the PostScript interpreter
reaches certain points within a PostScript language procedure.
To pause a context, an application sends the system-specific PostScript language
operator clientsync. The clientsync operator causes a context to enter
the FROZEN state. The context remains in that state until the application calls
the Client Library routine XDPSUnfreezeContext. For more information
on clientsync, see its description in Chapter 6. For a description of
XDPSUnfreezeContext, see Chapter 5.

4.8 Sharing Contexts and Spaces
Although the XDPS Client Library lets applications share contexts and spaces,
it does not coordinate the sharing. Instead, the applications themselves must
coordinate any sharing of resources.
The sharing applications must avoid race conditions and deadlocks. In addition, if
one application obtains the XID of a resource created by another, the application
that obtained the XID must create records and handles to access the shared
resource through the Client Library.
A context or space cannot be destroyed while shared. If such a resource is shared,
the routines DPSDestroyContext and DPSDestroySpace destroy the client
data structures created to access the shared resource but do not destroy the
resource itself. Mer a resource is no longer shared, an application can destroy it
by calling DPSDestroyContext or DPSDestroySpace.

4.9 Using Color
In XDPS, the Display PostScript system paints colors and gray shades on an X
server. An X server can render only a finite number of exact colors and shades
simultaneously; it represents each as a pixel value. (For more information, see
the Guide to the Xlib Library: C Language Binding.) In contrast, the PostScript
language represents colors and shades not as pixel values but as "pure" colors
and "pure" shades, without regard for whether the output device can render them
exactly. As a result, to paint on an X display, a PostScript context must first find
whether there is a pixel value that matches the pure color or shade specified by
the PostScript language.

4.9.1

Converting Colors and Shades into Pixel Values
To find the pixel value that matches a particular color or shade, a context
searches the color cube or gray ramp. The color cube and gray ramp specify
pixel values that correspond to a subset of all possible pure colors and shades.
(For more information, see colormap and XStandardColormap in the Guide to
the Xlib Library: C Language Binding.)
The color cube defines a set of colormap cells whose values form a series of color
ramps (progressive changes in color). Each axis of the color cube represents one
of three hues: red, green, or blue (r/g/b); all displayed colors are composites of
these hues. Values along the axes of the cube represent intensity of hue and
increase from 0% to 100% of the displayed color. Note that the color cube is not
Advanced Concepts and Tasks

4-7

a cube in the strict sense of the word: the axes need not have the same ''length,''
that is, the same number of values.
The gray ramp defines a set of colormap cells whose values form a single
color ramp of gray shades. Values along the gray ramp represent comparative
intensities of black and white. Along the ramp, the intensity of white increases
from 0% to 100%.
If the color cube or gray ramp contains a pixel value that exactly matches
the specified pure color or shade, the context uses the pixel value to paint the
pure color or shade. Otherwise, the context approximates the color or shade by
dithering, by painting a pattern of colors or gray shades from its color cube or
gray ramp.

4.9.2

Defining a Color Cube and Gray Ramp
When creating a context, an application must allocate and define a color cube and
gray ramp. If the application defines no color cube, the context renders colors by
dithering from the gray ramp. If the application defines neither a color cube nor
a gray ramp, the context cannot paint.
Typically, applications create contexts by calling XDPSCreateSirnpleContext.
This routine allocates and defines a color cube and gray ramp using the
XStandardColorrnap structures RGB DEFAULT MAP and RGB GRAY MAP. If
these structures do not exist, XDPSCreateSirnpleContext allocates them. To
allocate and define a different color cube and gray ramp, an application can use
either of two methods:
•

Create the context by calling XDPSCreateContext.

•

Create the context by calling either XDPSCreateSirnpleContext
or XDPSCreateContext; and then use the X-specific operator
setXgcdrawablecolor to redefine the color cube and gray ramp.

To allocate and define a color cube and gray ramp, an application performs the
following steps:
1.

Calls XCreateColorrnap to create a colormap. (This optional step is needed
only if the application does not use the default colormap.)

Calls XAllocColorCells to allocate the colormap cells needed to store the
color cube and gray ramp.

Calls XStoreColors to store a color for each pixel value in the color cube
and gray ramp.

Calls XDPSCreateContext to create a context and pass the
XStandardColorrnap structures describing the color cube and gray ramp.

The rest of this section describes how XDPS uses the color cube and gray ramp.
The section refers to the elements of the color cube and gray ramp by the
following names:

maxred
redmult
maxgreen
greenmult
maxblue
bluemult
firstcolor
maxgrays
4-8 Advanced Concepts and Tasks

graymult
firstgray
colormapid
These names are the same as those used for elements of the colorinfo array,
which is accessed by the X-specific operators setXgcdrawablecolor and
currentXgcdrawablecolor. (For more information, see the description of
these operators in Chapter 6.)
4.9.2.1

Using the Color Cube

To render an exact color, XDPS searches the colormap for the pixel value
matching the r/g/b value specified in the color cube. Conceptually, the color cube
is three-dimensional; the colormap, however, is conceptually one-dimensional.
Thus, to find the pixel value that matches an r/g/b value, XDPS uses the following
formula:
PixelValue = r * redmult + g * greenmult + b * bluemult + firstcolor

In this formula, r, b, and g are integers. The integer r is in the range [0, maxred];
g is in the range [0, maxgreen]; and b is in the range [0, maxblue].
A color cube must start at pixel first color in the X colormap colorrnapid.
Along the red, green, and blue axes of the cube, values should increase from zero
to the maximum values for each axis. For example, one common color allocation
is 3/3/2 (three reds, three greens, and two blues). This allocation results in the
following maximum value for each hue:
maxred = 2
maxgreen = 2
maxblue = 1

In the colorinfo array, the elements redmult, greenmult, and bluemult are the
scale factors that determine the spacing of the cube in the linear colormap. For
the 3/3/2 color cube mentioned earlier, appropriate values might be:
redmult = 32
greenmult = 4
bluemult = 1

NOTE

In an empty color cube, maxred, maxgreen, and maxblue each equal -1,
not zero.
4.9.2.2

Using the Gray Ramp

The gray ramp must start at pixel firstgray in XStandardColormap
colorrnapid. To find the pixel value that matches a gray value, XDPS uses
the following formula, where gray is an integer in the range [0, maxgrays]:
PixelValue = gray * graymult + firstgray

For example, suppose you want to define a 5-cell gray ramp whose values increase
from 0% to 100% in steps of 20%. If the corresponding five colormap entries are
contiguous, you can describe the map by setting maxgray to 4 and graymult to l.
A gray ramp must consist of at least two cells: one for black, one for white. If
the colormap is associated with the default visual type, you can use the following
values to form a 2-cell gray ramp consisting of BlackP ixel and Whi teP ixel:
Advanced Concepts and Tasks

4-9

maxgrays = 1
graymult = W hitePixel - BlackPixel
firstgray = BlackPixel

4.9.3

Rendering Colors Not in the Color Cube
By default, XDPS dithers to render any color not in the color cube. To render such
an additional color exactly, an application must cause the X server to allocate a
colormap cell for the additional color.
To control whether additional colors are rendered exactly or by dithering, an
application can set the actual element of the colorinfo array. The actual
element specifies the maximum number of additional colormap cells that the
server attempts to allocate. Thus, it limits the number of additional colors that
the server attempts to render exactly.
If actual is nonzero, the server attempts to allocate a colormap cell for each
additional color until it has allocated actual cells. After actual cells have been
allocated, the server renders any future additional colors by dithering. If actual
equals zero, the server dithers to render all colors not found in the color cube.
To override the maximum set by actual, an application can use the X-specific
operator setrgbXactual.
CAUTION

XDPS does not limit the number of colormap cells that one context or
one application can allocate.

4.9.4

The colorinfo Array and XStandardColormap Structures
The color cube and gray ramp are passed to XDPSCreateContext as
XStandardColormap structures. Tables 4-2 and 4-3 show how the entries
in these XStandardColormap structures correspond to elements in the
colorinfo array.
Table 4-2:

4-10

Mapping Between colorinfo Array and XStandardColormap Storing
Color Cube

colorinfo Element

XStandardColormap Element

maxred
redmult
maxgreen
greenmult
maxblue
bluemult
firstcolor

red max
red mult
green_max
green_mult
blue max
blue mult
base_pixel

Advanced Concepts and Tasks

Table 4-3:

Mapping Between colorinfo Array and XStandardColormap Storing
Gray Ramp

colorinfo Element

XStandardColormap Element

maxgrays
graymult
firstgray
colormapid

red max
red mult
base_pixel
colormap

Advanced Concepts and Tasks

4-11

Chapter 5

Client Library Routines for UWS
The Client Library is the set of C language routines by which XDPS applications
access a server, that is, the PostScript interpreter of an X server. The Client
Library includes routines that create, communicate with, and destroy PostScript
contexts on the server.
Most Client Library routines are common to all windowing systems that
implement the Display PostScript system. But for any particular windowing
system, such as X, additional routines and data structures must be added to the
Client Library.
This chapter describes UWS-specific routines and data structures that have
been added to the Client Library. For descriptions of system-independent Client
Library routines, see the Display PostScript System Client Library Reference
Manual. In addition, see that book for information on system-independent Client
Library concepts and tasks.
For the rest of this chapter, except where noted, the term "Client Library" refers
to the Display PostScript system Client Library as implemented in UWS.
The Client Library routines are defined in six C-Ianguage header files:

•
•
•
•
•
•

dpsclient.h
dpsfriends.h
dpsexcept.h
dpsops.h
psops.h
dpsXclient.h

The first five of these files are common to all implementations of the Display
PostScript system and are described in the Display PostScript System Client
Library Reference Manual. The sixth file, dpsXclient . h, is specific to XDPS
and is described in the following section.

5.1

System-Specific Header File
The header file dpsXclient. h defines the system-specific Client Library
routines and data structures of XDPS. Like the other Display PostScript system
header files, dpsXclient. h is located in the directory /usr/include/DPS.
The dpsXclient. h file is the only Client Library header file that all XDPS
applications must include.

Client Library Routines for UWS

5-1

5.2 X-Specific Singleops
The Client Library includes a set of routines called singleops (single-operator
wrapped procedures). Each singleop sends one or more operators to a context.
For instance, the singelop PSshowpage sends the operator showpage.
For each operator, the Client Library defines two singleops: one takes an implicit
context argument (always the current context); the other takes an explicit context
argument. For example, the Client Library contains the singleops P S showpage
and DP S showpage. Although both singleops execute the operator showpage,
PSshowpage takes an implicit context argument; DPSshowpage takes an
explicit one.
Implicit-context singleops are defined in the header file psops . h; explicit-context
singleops are defined in dpsops . h. If your application creates only one context,
using implicit-context singleops can make coding easier.
The Client Library includes X-specific singleops. Each of these singleops sends
an X-specific operator, for example, setXgcdrawable. Like other singleops,
X-specific singleops are of two types: implicit-context and explicit-context.
X-specific singleops that take an implicit context argument are defined in the
file pscustornops. h, which is included by psops. h. X-specific singleops that
take an explicit context are defined in dpscustornops . h, which is included by
dpsops .h.
Example 5-1 shows the definitions of the X-specific singleops. Table 5-1 describes
the arguments used in the definitions. For descriptions of the operators that the
X-specific singleops send, see Chapter 6. For general information about singleops,
see the Display PostScript System Client Library Reference Manual.
Example 5-1:

Definitions of X-specific Singleops

extern void DPSelientsyne( /* DPSContext etxt; */ );
extern void DPSeurrentXgedrawable( /* DPSContext etxt; int *ge, *d, *x, *y; */ );
extern void DPSeurrentXgedrawableeolor( /* DPSContext etxt; int *ge, *d, *x, *y, eolorInfo[12]; */ );
extern void DPSeurrentXoffset( /* DPSContext etxt; int *xOffset, *yOffset; */ );
extern void DPSsetXgedrawable( /* DPSContext etxt; int ge, d, x, y; */ );
extern void DPSsetXgedrawableeolor( /* DPSContext etxt; int ge, d, x, y, eolorInfo[12]; */ );
extern void DPSsetXoffset( /* DPSContext etxt; short int x, y; */ );
extern void DPSsetXrgbaetual( /* DPSContext etxt; int r, g, b; Boolean *sueeess; */ );
extern void PSelientsyne();
extern void PSeurrentXgedrawable( /* int *ge, *d, *x, *y; */ );
extern void PSeurrentXgedrawableeolor( /* int *ge, *d, *x, *y, eolorInfo[12]; */ );
extern void PSeurrentXoffset( /* int *xOffset, *yOffset; */ );
extern void PSsetXgedrawable( /* int ge, d, x, y; */ );
extern void PSsetXgedrawableeolor( /* int ge, d, x, y, eolorInfo[12]; */ );
extern void PSsetXoffset( /* int x, y; */ );
extern void PSsetXrgbaetual( /* int r, g, b; Boolean *sueeess; */ );

5-2 Client Library Routines for UWS

Table 5-1:
Name

Arguments Used by X-Specific Singleops
Type
Description

colorlnfo!12]

integer
array

Stores color attributes of the context. The
elements of this array are graymax,
graymult, firstgray, redmax, redmult,
greenmax,greenmult,bluemax,bluemult,
firstcolor, colormapid, and numactual.

integer

The X resource ID of an X drawable. If d equals
zero, all drawing operations are ignored.

integer

The GContext resource ID for the X
Graphic Context of drawable. If gc equals
zero, all drawing operations are ignored. To
obtain a value for gc, call the Xlib routine
XGContextFromGC ( ) , passing the Xlib data
type GC of the current X Graphic Context as the
argument.

r,g, b

integer

Levels for red, green, and blue, in the X color
space [0 .. 65535].

success

Boolean

When nonzero, shows that the singleop completed
without a PostScript language error. When zero,
shows that the singleop produced a PostScript
language error on the server.

x andy

integer

The horizontal and vertical coordinates (in X
units) for the default user space origin of the
current drawable. If x equals zero, and y equals
the height of the drawable (in pixels), the default
user space origin is at the lower left corner of the
drawable. In the PostScript language, this is the
typical location for the default user space origin.

xOffset and
yOffset

integer

Same as x y; see descriptions in this table.

5.3 Naming Conventions
Table 5-2 shows conventions used to name the UWS-specific Client Library
routines.
Table 5-2: Naming Conventions in the Client Library
Type of Routine

Naming Convention

System-specific Routine

DPSMnemonic_name
(continued on next page)

Client Library Routines for UWS

5-3

Table 5-2 (Cont.):

Naming Conventions in the Client Library

Type of Routine

Naming Convention

X-specific Client Library routine
Singleop with implicit context argument
Singleop with explicit context argument

XDPSMnemonic_name
PSoperator_name
DPSoperator_name

5.4 Format of Routine Descriptions
The rest of this chapter describes each system-specific Client Library routine and
data structure. Each description follows this format:
NameOfRoutine

/* C-Ianguage definition of the routine */;
Text describing what the routines does and what its
arguments represent.

5.5 Client Library Routine Descriptions
This section lists and describes the system-specific Client Library routines.
The descriptions are arranged alphabetically by name. The format of these
descriptions is explained in Section 5.4.
Following is a list of the system-specific routines and data structures:
DPSChangeEncoding
DPSContextFromContextID
DPSCreateTextContext
DPSDefaultTextBackstop
DPSNewUserObjectlndex
XDPSContextFromSharedID
XDPSContextFrornXID
XDPSCreateContext
XDPSCreateSimpleContext
XDPSFindContext
XDPSRegisterStatusProc
XDPSSetStatusMask
XDPSSpaceFromSharedID
XDPSSpaceFromXID
XDPSUnfreezeContext
XDPSXIDFromContext
XDPSXIDFromSpace

The rest of this chapter describes the items listed.

5-4 Client Library Routines for UWS

DPSChangeEncoding
void DPSChangeEncoding
(/* DPSContext ctxt;
DPSProgramEncoding newProgEncoding;
DPSNameEncoding newNameEncoding */);

DP SChangeEncoding sets the value of one or both
encoding parameters of the context specified by ctxt. If the
encoding parameters are set to values other than the default
values, DPSWritePostScript, singleops, and custom
wraps convert PostScript language code to the specified i
encoding before sending it to context ctxt.
For a list of the default encodings, see Section 4.1.

DPSContextFromContexti D
DPSContext
DPSContextFromContextlD(1*
DPSContext ctxt;
long int cid;
DPSTextProc textProc;
DPSErrorProc errorProc */);

DPSContextFromContextID returns the DPSContext
handle of the context whose PostScript language ID is cid.
Context cid is one created when a preexistent context, ctxt,
executed the PostScript operator fork. The arguments
textProc and errorProc specify the two routines with which
the calling client handles text and errors from the context
cid.
If the calling client has no context record for context cid,
DPSContextFromContextID creates one. The new
context record uses the text handler and error handler
passed in textProc and errorProc. If textProc or errorProc is
NULL, the new context record uses the text handler and error
handler of ctxt.
Except for the text handler, error handler, and chaining
pointers, the created context record inherits all its
characteristics from ctxt. (For an explanation of chained
contexts, see the Display PostScript System Client Library
Reference Manual.)

Client Library Routines for UWS

5-5

DPSCreateTextContext
DPSContext
DPSCreateTextContext(1*
DPSTextProc textProc;
DPSErrorProc errorProc */);

DPSCreateTextContext creates a context record and
DP SContext handle not associated with an execution
context. When this DPSContext handle is passed as the
argument to a Client Library routine, that routine converts
all context input into ASCII text, and then passes that text
to the text-handling routine textProc. The routine specified
by errorProc handles errors that result from improper context
usage. (For example, one such error occurs if the context is
invalid.)
Do not use the errorProc routine to handle errors that result
from executing textProc. For example, if your textProc routine
writes text to a file, do not use errorProc to handle file-related
errors, such as those that occur when a file is write-protected.
(For more information, see the Display PostScript System

Client Library Reference Manual.)
DPSDefaultTextBackstop
void DPSDefaultTextBackstop
(/* DPSContext ctxt;
char *buf;
unsigned count */);

DPSDefaultTextBackstop is a text-handling routine;
it is the default text backstop installed by the Client
Library. Because DPSDefaultTextBackstop is
of type DPSTextProc, it can be specified as the
text-handling routine (textProc) in context-creation
routines, such as XDPSCreateSimpleContext.
DPSDefaultTextBackstop writes text to ULTRIX
stdout and flushes stdout.
DPSNewUserObjectindex
long int DPSNewUserObjectlndex();

DPSNewUserObjectlndex returns a new user object
index. All new user object indices are allocated by the Client
Library.
User object indices are dynamic; do not compute with them or
store them in long-term storage, such as in a file. For more
information about user object indices, see the PostScript
Language Extensions for the Display PostScript System.

5-6

Client Library Routines for UWS

XDPSContextFromSharedlD
DPSContext
XDPSContextFromSharedID(/*
Display *dpy;
PSContextlD cid;
DPSTextProc textProc;
DPSErrorProc errorProc */);
XDPSContextFromSharedID returns the DPSContext

handle of an existing context, specified by PostScript
language ID (cid) and X display (dpy). If the calling client
has no such DPSContext, XDPSContextFromSharedID
creates a DPSContext and the associated
DP SContextRec.

The arguments textProc and errorProc specify the two
routines with which the calling client handles text and
errors from the specified context.
XDPSContextFromSharedID lets one client access a
context created by another client, thereby letting multiple
clients share a single context. When sending names to
shared contexts, XDPSContextFromSharedID uses name
string encoding.
XDPSContextFromXID
DPSContext
XDPSContextFromXI D(/*
Display *dpy;
XID xid */);
XDPSContextFrornXID returns the DPSContext handle
of an existing context, specified by X resource ID (xid) and X
display (dpy).

Client Library Routines for UWS

5-7

XDPSCreateContext
DPSContext
XDPSCreateContext(1*
Display *dpy;
Drawable drawable;
GC gc;
int x,y;
unsigned int eventmask;
XStandardColormap *grayramp;
XStandardColormap *ccube;
int actual;
DPSTextProc textProc;
DPSErrorProc errorProc;
DPSSpace space */);

XDPSCreateContext creates an execution context and the
associated DPSContextRec data structure. It returns a
DPSContext handle.
Unlike XDP SCreateSimpleContext,
XDPSCreateContext lets you explicitly specify all
characteristics of the context, including its colormap
entries. But, unless your application uses color in an
unusual way, you need not use XDPSCreateContext;
use XDPSCreateSimpleContext instead.
When called, XDPSCreateContext checks whether the X
s'erver dpy supports a Display PostScript system extension.
If not, the routine returns NULL; if so it checks that the
specified drawable and GC exist on the same screen. If they
do not, the X server returns a BadMatch error. If they do,
XDPSCreateContext creates a PostScript context having
the characteristics specified in the arguments passed.
If the argument drawable or GC is NULL, the created
context can receive and execute PostScript language input,
but cannot paint images until the calling application
specifies an X drawable and GC. (To specify these values,
the application must send an X-specific operator, such as
setXgcdrawable, described in Chapter 6.)
The following table describes the arguments of
XDPSCreateContext.

Argument
Name
dpy
drawable
GC
x andy

5-8

Client Library Routines for UWS

Argument
Name
eventmask
grayramp
ccube
and
grayramp

actual

textProc
errorProc
space

Description
Ignored; reserved for future use. Use zero
as the value of this argument.
(See ccube.)
ccube identifies a set of color cells defined as
a series of color ramps; grayramp identifies
a set of color cells defined as a gray ramp.
The context uses ccube and grayramp to
produce actual colors and dithered colors.
If ccube equals NULL, colors are rendered
in shades of gray only. If grayramp equals
NULL, the context does not paint. The gray
ramp must have at least two elements: one
for black and one for white.
The X client must allocate and define
ccube and grayramp and must install the
associated colormap. In general, if the
client specifies a plane mask, ccube and
grayramp should be within the planes
selected by the plane mask, to ensure that
the Display PostScript system interacts
properly with the plane mask.
For more information, see Section 4.9.
Specifies whether the application prefers
to paint with actual (not dithered) colors
and, if so, specifies how many actual colors
it needs. The actual argument is a hint
to the X server: dithering and actual color
allotment are governed by the X server, not
by the application.
If actual equals zero, the application paints
by dithering colors from grayramp and
ccube. If actual is not zero, the application
paints using a maximum of actual actual
colors; all additional colors are dithered.
The routine that this context calls to handle
text output.
The routine that this context calls if it
encounters an error condition.
The private VM in which this context
executes. If space is NULL, a new space
is created for the context; otherwise, the
context shares the specified space.

Client Library Routines for UWS 5-9

XDPSCreateSimpleContext
DPSContext
XDPSCreateSimpleContext(1*
Display *dpy;
Drawable drawable;
GC gc;
int x,y;
DPSTextProc textProc;
DPSErrorProc errorProc;
DPSSpace space */);

XDPSCreateSimpleContext creates an execution context
and the associated DPSContextRec data structure. It
returns a DPSContext handle.
When called, XDPSCreateSimpleContext checks
whether the X server dpy supports a Display PostScript
system extension. If not, the routine returns NULL; if so, it
checks that the specified drawable and GC exist on the same
screen. If they do not, the X server returns a BadMatch
error. If they do, XDPSCreateSimpleContext creates a
PostScript context having the characteristics specified in the
arguments passed.
If the argument drawable or GC is NULL, the created
context can receive and execute PostScript language input,
but cannot paint images until the calling application
specifies an X drawable and GC. (To specify these values,
the application must send an X-specific operator, such as
setXgcdrawable, described in Chapter 6.)
The following table describes the arguments of
XDPSCreateSimpleContext.

Argument
Name
dpy
drawable
GC
x andy

textProc
errorProc
space

5-10

Client Library Routines for UWS

Description
An X display.
An X drawable on display.
The X Graphic Context associated with
drawable.
The horizontal and vertical coordinates (in
X units) for the default user space origin
of drawable. If x equals zero and y equals
the height of drawable, the default user
space origin is at the lower left corner of
drawable. In the PostScript language, this
is the typical location for the default user
space origin.
The routine that this context calls to handle
text output.
The routine that this context calls if it
encounters an error condition.
The private VM in which this context
executes. If space is NULL, a new space
is created for the context; otherwise, the
context shares the specified space.

Unlike the XDPSCreateContext routine,
XDPSCreateSirnpleContext does not let you explicitly
specify the colormap of the created context, nor does it let you
set characteristics of the colormap. Instead, the routine uses
standard colormaps as described in the following paragraph.
XDPSCreateSirnpleContext accesses the X server
dpy and finds out whether the standard colormaps
RGB DEFAULT MAP and RGB GRAY MAP are defined.
If they are defiiled, XDPSCreateSimpleContext uses
them; otherwise, the routine defines them.
After these values are defined, any context
that the application creates by calling
XDPSCreateSirnpleContext uses RGB DEFAULT MAP
and RGB GRAY MAP. Note, however, thatcontexts created
by calling XDPSCreateContext use the color cube and
gray ramp specified in the call to that routine.
For more information about XDPSCreateSirnpleContext,
see the Display PostScript System Client Library Reference
Manual. For information on explicitly specifying the color
characteristics of a context, see the description of
XDPSCreateContext in this chapter.
XDPSFindContext
DPSContext
XDPSFindContext(1*
Display *dpy;
long int cid */);
XDPSFindContext returns the DPSContext handle of
the context whose ID is specified in cid.
The argument cid is the result returned by an operator such
as currentcontext; dpy specifies the X display where the
context is running.

Client Library Routines for UWS 5-11

XDPSRegisterStatusProc
typedef void (*XDPSStatusProc)(1*
DPSContext ctxt;
int code */);

void
XDPSRegisterStatusProc (/*
DPSContext ctxt;
XDPSStatusProc proc */);

XDPSRegisterStatusProc specifies the routine
that an application calls to handle status events
(XDPSStatusEvent) from the context ctxt. That is,
XDPSRegisterStatusProc registers, or associates,
the XDPSStatusProc event-handling routine proc with the
context ctxt.
The routine proc has two arguments: ctxt and code. The
argument ctxt specifies the context with which proc is
registered; code shows the status code of the event for which
proc was called. The client can call proc at any time to
process status events.
If an XDPSStatusProc routine is already registered with
the context ctxt, XDPSRegisterStatusProc supersedes
the existing registration with the value of proc.

5-12

Client Library Routines for UWS

XDPSSetStatusMask
void
XDPSSetStatusMask(1*
DPSContext ctxt;
unsigned long enableMask;
unsigned long disable Mask;
unsigned long nextMask */);

XDPSSetStatusMask sets the context status mask
of the context specified in the argument ctxt. (For a
explanation of context status and the context status mask,
see Section 2.2.3.)
The argument enableMask specifies which kinds of context
status events the XDPS server sends to the calling
application; disableMask specifies the kinds of context status
events the server does not send. The argument nextMask
causes the server to send only the next instance of each
specified kind of context status event. The enableMask,
disableMask, and nextMask arguments each represent one or
more of the values listed in the following code extract:
#define PSRUNNINGMASK
OxOOOl
#define PSNEEDSINPUTMASK
Ox0002
#define PSZOMBIEMASK
Ox0004
#define PSFROZENMASK
Ox0008
To assign more than one value to a single argument, perform
a bitwise inclusive OR operation ( I ) on the values you wish
to assign, as in the following example.
XDPSSetStatusMask(PSRUNNINGMASK I PSNEEDSINPUTMASK,O,O);

The following table describes the valid values for enableMask,
disableMask, and nextMask.

Mask value

Status Events Affected

PSFROZENMASK

Events that show the
context is frozen
Events that show the
context needs input
Events that show the
context is in the runnable
state.
Events that show the
context is in the zombie
state.

PSNEEDSINPUTMASK
PSRUNNINGMASK

PSZOMBIEMASK

Note that, if an application sends input to a context that is
in the zombie state, the application receives a zombie status
event, regardless of how the status mask is set.

Client Library Routines for UWS

5-13

XDPSSpaceFromSharedlD
DPSSpace
XDPSSpaceFromSharedID(/*
Display *dpy;
SpaceXID sid */);
XDPSSpaceFrornSharedID returns the DPSSpace handle

of an existing private context space, specified by X resource
ID (sid) and display (dpy). If the calling client has no
such DPSSpace, XDPSSpaceFrornSharedID creates the
DPSSpace and associated DPSSpaceRec data structure.
XDPSSpaceFrornSharedID lets a context created by one X
client share the private space of a context created by another
X client. When sending names to shared context whose
private space is shared, XDPSSpaceFrornSharedID uses
ASCII encoding.
XDPSSpaceFromXID
DPSSpace
XDPSSpaceFromXID(/*
Display *dpy;
XID xid */);
XDPSSpaceFrornXID returns the DPSSpace pointer of an

existing private context space, specified by X resource ID
(sid) and display (dpy).

XDPSUnfreezeContext
void
XDPSUnfreezeContext (/*
DPSContext ctxt */);
XDPSUnfreezeContext causes the specified frozen

context to resume executing. The argument ctxt is the ID
of a context whose status is PSFROZEN.
XDPSXI DFromContext
XID
XDPSXI DFromContext(/*
Display **Pdpy;
DPSContext ctxt */);
XDPSXIDFrornContext returns the X resource ID of the
context whose DP SContext handle is ctxt. In addition, the
routine returns the argument Pdpy, which points to the X
Display structure associated with ctxt.

5-14 Client Library Routines for UWS

XDPSXIDFromSpace
XID
XDPSXI DFromSpace(/*
Display **Pdpy;
DPSSpace spc */);
XDPSXIDFromSpace returns the X resource ID of the
context associated with the DPSSpace pointer spc. In

addition, the routine returns the argument Pdpy, which
points to the X Display structure associated with spc.

Client Library Routines for UWS

5-15

Chapter 6

X-Specific Operators for UWS
The Display PostScript system extends the PostScript language to include
operators for generic window-related tasks; but, for tasks that relate specifically
to X, the window system of UWS, additional operators are needed. To fill this
need, UWS extends the PostScript language to include X-specific operators.
This chapter describes the X-specific operators for UWS. For descriptions of
extensions to the PostScript language, see the PostScript Language Extensions
for the Display PostScript System and the PostScript Language Color Extensions.
For a description of the basic PostScript language, see the PostScript Language
Reference Manual. For general information about window system support in the
Display PostScript system, see that topic in the Display PostScript System Client
Library Reference Manual.
The Client Library defines single-operator procedures that execute the X-specific
operators. For information on these procedures, see Chapter 5.

6.1

About the Operators
The operators described in the rest of this chapter are arranged alphabetically by
operator name. Each description follows this format:
operator
operand 1 .•• operand n operator result 1 ••• result m

Text describing what the operator does.
EXAMPLE:
Sample PostScript language code showing how to use
the operator. (Optional.)
ERRORS:
A list of the errors this operator might execute

Each operator description begins with a syntax summary. In it, operand! through
operandn are the operands that the operator requires; operand! is the top
element on the operand stack. A dash (-) in the operand position means the
operator accepts no operands.
The operator pops the operands from the stack and processes them. After
executing, the operator pushes result! through resultm on the stack; result m is
the top element. A dash (-) in the result position means the operator returns
no results.

X-Specific Operators for UWS

6-1

Table 6-1 describes the values used as operands and results by the X-specific
operators for UWS. All operands are required.
Table 6-1: Operands and Results for X-Specific Operators
Name
Type
Description

colorinfo

integer
array

drawable

integer

red green
and blue

float

success

integer

x andy

integer

Stores color attributes of the context. The 12
elements of colorinfo are graymax, graymult,
firstgray, redmax, redmult,greenmax,
greenmult,bluemax,bluemult,firstcolor,
colormapid, and numactual. (For more
information, see Section 4.9.4.)
The X window ID or pixmap ID of an X drawable.
If drawable equals zero, all drawing operations are
ignored.
The GContext resource ID for the X Graphic
Context of drawable. If gc equals zero, all drawing
operations are ignored. To obtain a value for gc, call
the Xlib routine XGContextFromGC, passing the
Xlib data type GC of the current Graphic Context as
the argument.
Three real numbers in the range 0.0 to 1.0
that, together, specify a color (as in the operator
setrgbcolor).
When nonzero, indicates that the operator completed
without error.
The horizontal and vertical coordinates (in X units)
for the default user space origin of the current
drawable. If x equals zero and y equals the height of
the drawable, the default user space origin is at the
lower left corner of the drawable. In the PostScript
language, this is the typical location for the default
origin.

Note that drawable, gc, x, and yare part of the PostScript graphics state, which
can be saved and restored using the PostScript language operators gsave and
grestore.

6.2 Operator Errors
Table 6-2 shows the errors that the X-specific operators can return.
Table 6-2:
Error

Errors for X-Specific Operators
Probable Cause

rangecheck

stackunderflow
typecheck

Bad match: the drawable and GC do not have the same
depth, or their visual does not match the colormap
associated with the context.
Too few operands on the operand stack.
Invalid ID for drawable or for GC.
(continued on next page)

6-2 X-Specific Operators for UWS

Table 6-2 (Cont.):
Error

Errors for X-Specific Operators
Probable Cause

undefined

Context not associated with a display device.

6.3 Operator Descriptions
Following is an alphabetical list and description of the X-specific operators for
UWS. The format for these descriptions is explained in Section 6.1.
clientsync

- clientsync -

The clientsync operator pauses the current context,
sets the status of the context to FROZEN, and causes
the X server to return a PSFROZEN status event. The
context stays frozen until the application calls the Client
Library routine XDPSUnfreezeContext ( ). Thus,
client sync synchronizes the application with the
current context.
One possible use of clientsync is to display PostScript
language output one page at a time by pausing the
current context after each page, as in the following
example. This example redefines the operator showpage,
so that the operator first pauses the current context.
EXAMPLE:

/showpage {
clientsync
showpage
} bind def
ERRORS:

None
currentXgcdrawable
-

currentXgcdrawable gc drawable x y

The currentXgcdrawable operator returns the X
Graphic Context, drawable, and default user space origin
of the current context.
Note that the results returned by
currentXgcdrawable can be used as the operands
ofsetXgcdrawable.
ERRORS:

undefined

X-Specific Operators for UWS

6-3

currentXgcdrawablecolor
-

currentXgcdrawablecolor gc drawable x y colorinfo

The currentXgcdrawablecolor operator returns
the GC, drawable, default user space origin, and color
attributes of the current context.
Note that the results returned by
currentXgcdrawablecolor can be used as the
operands of setXgcdrawablecolor.
ERRORS:

undefined
cu rrentXoffset

currentXoffset x y

The currentXoffset operator returns the default
user space origin of the current context.
Note that the results returned by currentXoffset can
be used as the operands of setXoffset.
ERRORS:

undefined
setrg bXactual

red green blue setrgbXactual success

The setrgbXact ual operator allocates a new colormap
entry to display the color specified by red, green, blue.
If the allocation succeeds (if success is nonzero), future
painting of this color uses the new colormap entry instead
of dithering from the colorcube.
Note that setrgbXactual does not affect the graphics
state. Thus, to paint with the specified color, you must
first execute the operator setrgbcolor.
ERRORS:

stackunderflow undefined typecheck
setXgcdrawable

gc drawable x y setXgcdrawable-

The setXgcdrawable operator sets the X Graphic
Context, drawable, and default user space origin of
the current context. The values supplied as operands
supersede any existing values for these attributes.
The setXgcdrawable operator causes all subsequent
operations of the current context to occur in the specified
X drawable, with the specified Graphic Context and
default user space origin.
To make the effects of setXgcdrawable temporary, use
it between the operators gsave and grestore.

6-4

X-Specific Operators for UWS

ERRORS:

rangecheck stackunderflow typecheck undefined
setXgcdrawablecolor
gc drawable x y colorinfo setXgcdrawablecolor -

The setXgcdrawablecolor operator sets the GC,
drawable, default user space origin, and color attributes of
the current context.
ERRORS:

rangecheck stackunderflow typecheck undefined
setXoffset

x y setXoffset -

The setXoff set operator sets the default user space
origin for the current context.
ERRORS:

stackunderflow undefined

X-Specific Operators for UWS 6-5

Index
A
Application
basic requirements, 3-3 to 3-4
building, 3-9 to 3-11
developing typical, 3-1 to 3-3
sample
See Sample applications

8
Basic tasks, summary, 3-13 to 3-14
Bit gravity, 4-4
Buffering, 4-1

c
Client Library, 2-2
header files, 5-1
naming conventions
See Naming conventions, Client Library
Client Library routines, 5-4 to 5-15
clientsync operator, 6-3
Clipping path, 4-4
Color, using, 4-7 to 4-11
Color cube
See Color, using
Colormap
allocating entries in, 4-8 to 4-10
See also setrgbXactual operator
See Color, using
Compiling
See Application, building
Context, 2-2 to 2-3
color attributes
obtaining, 6-4
setting, 6-5
creating
execution context, 5-7,5-9
text context, 5-5
finding
See DPSContext handle, finding
pausing, 6-3
sharing, 4-7
unfreezing, 5-14
XID, finding, 5-14
Context record, 2-3
Context status events, 2-4
See also XDPSRegisterStatusProc routine and
XDPSSetStatusMask routine
Context status mask, 2-4

Context status mask (Cont.)
See also XDPSSetStatusMask routine
Coordinates, converting, 4-2 to 4-3
Coordinate systems, 2-4 to 2-7
Current context, 2-4
See also Context
currentXgcdrawablecolor operator, 6-4
currentXgcdrawable operator, 6-3
currentXoffset operator, 6-4

D
Default text backstop
See DPSDefaultTextBackstop routine
Default user space origin
See User space origin
Documentation, summary of, 1-2 to 1-3
DPSChangeEncoding routine, 5-4
DPSContextFromContextlD routine, 5-5
DPSContext handle, 2-3
finding, 5-5,5-6,5-7,5-11
DPSContextRec data type
See Context record
DPSCreateTextContext routine, 5-5
DPSDefaultTextBackstop routine, 5-6
DPSNewUserObjectlndex routine, 5-6
DPSSpace handle
finding, 5-13,5-14
dpsXclient.h file
See System-specific header file
Drawable
See also Window
setting
See setXgcdrawable operator

E
Encoding, PostScript language, 4-1, 5-4
Example applications
See Sample applications
examplemain sample application, 3-4 to 3-11
Execution context
See Context

F
Files, accessing, 4-2

Index-1

Space (Cont.)

G
GC
See X Graphic Context
Graphic Context
See X Graphic Context
Graphics state, 2-3, 6-4
Gray ramp
See Color, using

finding
See DPSSpace handle, finding, 5-14
sharing, 4-7
Synchronization
client and context, 4-7
Display PostScript System and X, 4-6
System-specific header file, 5-1

H
Header files
See also Application, building
See Client Library, header files

Identifiers, 2-4
Imaging model, 1-1
Input, defined, 2-3

L
Linking
See Application, building

M
Makefile, sample
See Application, building

Text context
See Context

u
User object index, new
See DPSNewUserObjectindex routine
User space coordinate system
See Coordinate systems
User space origin, 2-5
obtaining, 6-3, 6-4
setting, 6-4, 6-5

v
Virtual memory
See VM
VM, 2-4

w
Window, resizing, 4-3 to 4-6

N
Naming conventions, Client Library, 5-3

o
Operators, 6-1 to 6-5
See also individual operator names
Origin
See also User space origin
See Coordinate systems
Output, defined, 2-3

p
Pixel value
See Color, using
PostScript interpreter, 2-1
PostScript language encoding
See Encoding, PostScript language
PostScript language imaging, 1-1
pswrap translation program, 2-2

s
Sample applications
running, 3-13
summary, 3-12
setrgbXactual operator, 6-4
setXgcdrawablecolor operator, 6-5
setXgcdrawable operator, 6-4
Singleops, 5-2 to 5-3
Space, 2-4

Index-2

x
X coordinate system
See Coordinate systems
XDPSContextFromSharedlD routine, 5-6
XDPSContextFromXID routine, 5-7
XDPSCreateContext routine, 5-7
XDPSCreateSimpleContext routine, 5-9
XDPSFindContext routine, 5-11
XDPSRegisterStatusProc routine, 5-11
XDPSSetStatusMask routine, 5-12
XDPSSpaceFromSharedlD routine, 5-13
XDPSSpaceFromXID routine, 5-14
XDPSUnfreezeContext routine, 5-14
XDPSXIDFromContext routine, 5-14
XDPSXIDFromSpace routine, 5-14
X Graphic Context, 2-3
setting, 6-4, 6-5
X-specific Operators
See Operators
XStandardColormap
See Color, using

How to Order Additional Documentation

Technical Support
If you need help deciding which documentation best meets your needs, call 800-343-4040 before placing

your electronic, telephone, or direct mail order.

Electronic Orders
To place an order at the Electronic Store, dial 800-DEC-DEMO (800-332-3366) using a 1200- or 2400baud modem. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825).

Telephone and Direct Mail Orders
Your Location

Call

Contact

Continental USA,
Alaska, or Hawaii

800-DIGITAL

Digital Equipment Corporation
P.O. Box CS2008
Nashua, New Hampshire 03061

Puerto Rico

809-754-7575

Local Digital Subsidiary

Canada

800-267-6215

Digital Equipment of Canada
Attn: DECdirect Operations KA02/2
P.O. Box 13000
100 Herzberg Road
Kanata, Ontario, Canada K2K 2A6

International

Local Digital subsidiary or
approved distributor

Internal*

SSB Order Processing - WMO/E15
or
Software Supply Business
Digital Equipment Corporation
Westminster, Massachusetts 01473

* For internal orders, you must submit an Internal Software Order Form (EN-01740-07).

Reader's Comments

ULTRIX Worksystem Software
Guide to Developing Applications for the
Display PostScript® System
AA-PAJUA-TE

Please use this postage-paid fonn to comment on this manual. If you require a written reply to a software
problem and are eligible to receive one under Software Perfonnance Report (SPR) service, submit your
comments on an SPR fonn.
Thank you for your assistance.

Please rate this manual:
Accuracy (software works as manual says)
Completeness (enough infonnation)
Clarity (easy to understand)
Organization (structure of subject matter)
Figures (useful)
Examples (useful)
Index (ability to find topic)
Page layout (easy to find infonnation)

Excellent

Good

Fair

Poor

D
D
D
D
D
D
D
D

0
D
D
0

0
D
0
D

What would you like to see more/less of?

What do you like best about this manual? _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __

What do you like least about this manual?

Please list errors you have found in this manual:
Page
Description

Additional comments or suggestions to improve this manual:

What version of the software described by this manual are you using?
Name(fitle _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ Dept.
Company
Date
Mailing Address _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __
_ _ _ _ _ _ _ _ _ _ _ _ _ Email _ _ _ _ _ _ _ _ _ _ _ _ Phone

____ P2_~~_~e~=fQld_~~~~~!~e~ ______________________________________________ :

No Postage

Necessary
if Mailed in the
United States

BUSINESS REPLY MAIL
FIRST CLASS PERMIT NO.33 MAYNARD MASS.
POSTAGE WILL BE PAID BY ADDRESSEE
Digital Equipment Corporation
Publications Manager
Open Software Publications Group
ZK03-2/Z04

110 SPIT BROOK ROAD
NASHUA, NH 03062-9987

Do Not Tear - Fold Here and Tape

Cut
Along
Dotted
Line