5 Client Library Routines for WS

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 WS-specific routines and data structures that have been added to the Client Library.

For the rest of this chapter, except where noted, the term "Client Library" refers to the Display PostScript system Client Library as implemented in WS.

The Client Library routines are defined in six C-language 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. 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.

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 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 PSshowpage and DPSshowpage. 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 pscustomops.h, which is included by psops.h. X-specific singleops that take an explicit context are defined in dpscustomops.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.

Example 5-1: Definitions of X-specific Singleops

extern void DPSclientsync( /* DPSContext ctxt; */ );

 

extern void DPScurrentXgcdrawable( /* DPSContext ctxt; int *gc, *d,
                                  *x, *y; */ );

 

extern void DPScurrentXgcdrawablecolor( /* DPSContext ctxt;
                                       int *gc, *d, *x, *y,
                                       colorInfo[12]; */ );

 

extern void DPScurrentXoffset( /* DPSContext ctxt; int *xOffset,
                              *yOffset; */ );

 

extern void DPSsetXgcdrawable( /* DPSContext ctxt; int gc, d, x, y; */ );

 

extern void DPSsetXgcdrawablecolor( /* DPSContext ctxt;
                                   int gc, d, x, y, colorInfo[12]; */ );

 

extern void DPSsetXoffset( /* DPSContext ctxt; short int x, y; */ );

 

extern void DPSsetXrgbactual( /* DPSContext ctxt; int r, g, b;
                             Boolean *success; */ );

 

extern void PSclientsync();

 

extern void PScurrentXgcdrawable( /* int *gc, *d, *x, *y; */ );

 

extern void PScurrentXgcdrawablecolor( /* int *gc, *d, *x, *y,
                                      colorInfo[12]; */ );

 

extern void PScurrentXoffset( /* int *xOffset, *yOffset; */ );

 

extern void PSsetXgcdrawable( /* int gc, d, x, y; */ );

 

extern void PSsetXgcdrawablecolor( /* int gc, d, x, y,
                                  colorInfo[12]; */ );

 

extern void PSsetXoffset( /* int x, y; */ );

 

extern void PSsetXrgbactual( /* int r, g, b; Boolean *success; */ );

Table 5-1: Arguments Used by X-Specific Singleops

Name	Type	Description
`colorInfo[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`.
`d`	integer	The X resource ID of an X drawable. If `d` equals zero, all drawing operations are ignored.
`gc`	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` and `y`	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 WS-specific Client Library routines.

Table 5-2: Naming Conventions in the Client Library

Type of Routine	Naming Convention
System-specific Routine	`DPSMnemonic_name`
X-specific Client Library routine	`XDPSMnemonic_name`
Singleop with implicit context argument	`PSoperator_name`
Singleop with explicit context argument	`DPSoperator_name`

5.4 Client Library Routine Descriptions

This section describes the following system-specific Client Library routines:

DPSChangeEncoding
DPSContextFromContextID
DPSCreateTextContext
DPSDefaultTextBackstop
DPSNewUserObjectIndex
XDPSContextFromSharedID
XDPSContextFromXID
XDPSCreateContext
XDPSCreateSimpleContext
XDPSFindContext
XDPSRegisterStatusProc
XDPSSetStatusMask
XDPSSpaceFromSharedID
XDPSSpaceFromXID
XDPSUnfreezeContext
XDPSXIDFromContext
XDPSXIDFromSpace

In the following list, the routines are arranged alphabetically by name. Each description provides the C-language defintion of the routine, followed by text describing what the routine does and what its arguments represent.

DPSChangeEncoding

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

The DPSChangeEncoding routine 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 encoding before sending it to context ctxt.

For a list of the default encodings, see Section 4.1.

DPSContextFromContextID

DPSContext
DPSContextFromContextID(/*
    DPSContext ctxt;
    long int cid;
    DPSTextProc textProc;
    DPSErrorProc errorProc */);

The DPSContextFromContextID routine 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.

DPSCreateTextContext

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

The DPSCreateTextContext routine creates a context record and a DPSContext 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, 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.

DPSDefaultTextBackstop

void DPSDefaultTextBackstop
(/* DPSContext ctxt;
    char *buf;
    unsigned count */);

The DPSDefaultTextBackstop routine 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 WS stdout and flushes stdout.

DPSNewUserObjectIndex

long int DPSNewUserObjectIndex( );

The DPSNewUserObjectIndex routine returns a new user object index. All new user object indexes are allocated by the Client Library.

User object indexes are dynamic; do not compute with them or store them in long-term storage, such as in a file.

XDPSContextFromSharedID

DPSContext
XDPSContextFromSharedID(/*
    Display *dpy;
    PSContextID cid;
    DPSTextProc textProc;
    DPSErrorProc errorProc */);

The XDPSContextFromSharedID routine 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 DPSContextRec.

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
XDPSContextFromXID(/*
    Display *dpy;
    XID xid */);

The XDPSContextFromXID routine returns the DPSContext handle of an existing context, specified by X resource ID (xid) and X display (dpy).

XDPSCreateContext

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

The XDPSCreateContext routine creates an execution context and the associated DPSContextRec data structure. It returns a DPSContext handle.

Unlike XDPSCreateSimpleContext, 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 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, 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:

dpy An X display.

drawable An X drawable on display.

GC The X Graphic Context associated with drawable.

x and y 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 (in pixels), 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.

eventmask Ignored; reserved for future use. Use zero as the value of this argument.

grayramp (See ccube.)

ccube and graymap 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.)

actual 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.

textProc The routine that this context calls to handle text output.

errorProc The routine that this context calls if it encounters an error condition.

space 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.

XDPSCreateSimpleContext

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

The XDPSCreateSimpleContext routine 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.

The following table describes the arguments of XDPSCreateSimpleContext:

dpy An X display.

drawabl An X drawable on display.

GC The X Graphic Context associated with drawable.

x and y 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.

textProc The routine that this context calls to handle text output.

errorProc The routine that this context calls if it encounters an error condition.

space 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, XDPSCreateSimpleContext 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.

XDPSCreateSimpleContext accesses the X server dpy, and finds out whether the standard colormaps RGB_DEFAULT_MAP and RGB_GRAY_MAP are defined. If they are defined, XDPSCreateSimpleContext uses them; otherwise, the routine defines them.

After these values are defined, any context that the application creates by calling XDPSCreateSimpleContext uses RGB_DEFAULT_MAP and RGB_GRAY_MAP. Note, however, that contexts created by calling XDPSCreateContext use the color cube and gray ramp specified in the call to that routine. For information on explicitly specifying the color characteristics of a context, see the description of XDPSCreateContext in this chapter.)

XDPSFindContext

DPSContext
XDPSFindContext(/*
    Display *dpy;
    long int cid */);

The XDPSFindContext routine 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.

XDPSRegisterStatusProc

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

 

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

The XDPSRegisterStatusProc routine 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.

XDPSSetStatusMask

void
XDPSSetStatusMask(/*
    DPSContext ctxt;
    unsigned long enableMask;
    unsigned long disableMask;
    unsigned long nextMask */);

The XDPSSetStatusMask routine sets the context status mask of the context specified in the argument ctxt. (For an 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          0x0001
#define PSNEEDSINPUTMASK       0x0002
#define PSZOMBIEMASK           0x0004
#define PSFROZENMASK           0x0008

To assign more than one value to a single argument, perform a bitwise inclusive OR operation (|) on the values you wish to assign, as in the following example:

XDPSSetStatusMask(PSRUNNINGMASK | PSNEEDSINPUTMASK,0,0);

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

PSFROZENMASK Events that show the context is frozen

PSNEEDSINPUTMASK Events that show the context needs input

PSRUNNINGMASK Events that show the context is in the runnable state

PSZOMBIEMASK Events that show the context is in the zombie state

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.

XDPSSpaceFromSharedID

DPSSpace
XDPSSpaceFromSharedID(/*
    Display *dpy;
    SpaceXID sid */);

XDPSSpaceFromSharedID 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, XDPSSpaceFromSharedID creates the DPSSpace and associated DPSSpaceRec data structure.

XDPSSpaceFromSharedID 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, XDPSSpaceFromSharedID uses ASCII encoding.

XDPSSpaceFromXID

DPSSpace
XDPSSpaceFromXID(/*
    Display *dpy;
    XID xid */);

XDPSSpaceFromXID 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.

XDPSXIDFromContext

XID
XDPSXIDFromContext(/*
    Display **Pdpy;
    DPSContext ctxt */);

XDPSXIDFromContext returns the X resource ID of the context whose DPSContext handle is ctxt. In addition, the routine returns the argument Pdpy, which points to the X Display structure associated with ctxt.

XDPSXIDFromSpace

XID
XDPSXIDFromSpace(/*
    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.

`dpy`	An X display.
`drawable`	An X drawable on `display`.
`GC`	The X Graphic Context associated with `drawable`.
`x and y`	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` (in pixels), 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.
`eventmask`	Ignored; reserved for future use. Use zero as the value of this argument.
`grayramp`	(See `ccube`.)
`ccube and graymap`	`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.)
`actual`	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.
`textProc`	The routine that this context calls to handle text output.
`errorProc`	The routine that this context calls if it encounters an error condition.
`space`	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`.

`dpy`	An X display.
`drawabl`	An X drawable on `display`.
`GC`	The X Graphic Context associated with `drawable`.
`x and y`	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.
`textProc`	The routine that this context calls to handle text output.
`errorProc`	The routine that this context calls if it encounters an error condition.
`space`	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`.

`PSFROZENMASK`	Events that show the context is frozen
`PSNEEDSINPUTMASK`	Events that show the context needs input
`PSRUNNINGMASK`	Events that show the context is in the runnable state
`PSZOMBIEMASK`	Events that show the context is in the zombie state