<!doctype LINUXDOC PUBLIC "-//XFree86//DTD linuxdoc//EN" [
<!ENTITY % defs SYSTEM "defs.ent"> %defs;
]>

<article>

<title>XFree86 and DPS
<author>Juliusz Chroboczek, <email/jch@xfree86.org/
<date>27 February 2001</date>

<ident>$XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/dps.sgml,v 1.2 2003/01/20 03:43:07 dawes Exp $</ident>

<toc>

<sect>Introduction

<p>Display Postscript (or DPS for short) is a rendering extension for
X11.  DPS is slightly atypical in that it is based on <it/code
mobility/, the ability to send executable code from client to server.
Thus, a DPS client does not request that a line should be rendered;
instead, it uploads code to the server which, when executed, causes a
line to be drawn.

<p>This document does not aim at teaching programming with DPS; it is
only a summary description of the DPS support code included with
XFree86.  More information about DPS, including a DPS bibliography, is
available from
<url url="http://dps.sourceforge.net" name="the DPS extension site">.

<tscreen>
<it>Note: Adobe, PostScript and Display PostScript are trademarks of
Adobe Systems Incorporated which may be registered in certain
jurisdictions.</it>
</tscreen>

As all X11 extensions, DPS consists of client-side and server-side
components.  The DPS client side consists of a number of libraries and
a number of tools for programming and configuration.  The DPS server
side may consist either of an X server extension, or of a client-side
process known as the ``DPS agent.''  In this latter case, the term
``server-side'' is somewhat misleading.

At the time of writing, only the client side is included with XFree86;
the server side must be obtained separately.  Please see <ref
id="sec:server-side" name="server side"> later in this document for
more information.

<sect>The DPS client side

<p>The DPS client side consists of four libraries and a number of
basic tools for programming and configuration; these are all included
with XFree86.

<sect1>Libraries

<p>The <tt/libpsres/ library is a library for management of
<it/PostScript resources/, on-disk files representing PostScript data
structures such as fonts, font encodings, procsets, <it/etc./ It is
closely related to the <tt/makepsres/ tool (see <ref id="sec:tools"
name="client-side tools"> later in this document).

The basic DPS client library is <tt/libdps/.  This library contains a
number of functions for connection establishment, resource management,
as well as stubs for all standard PostScript operators.  Normally, all
DPS clients should link with <tt/libdps/; in addition, <tt/libdps/ may
be used for printing by non-DPS clients (this is done, for example, by
Sun's JDK).  This library is documented in [CLRM] and [CLSX].

The <tt/libdpstk/ library contains a number of additional utilities
for managing DPS contexts, user paths and user objects, and for
previewing EPS files.  It is documented in [DPTX].

The <tt/libdpstkXm/ library contains four Motif widgets.  The <it/DPS
Scrolling Widget/ is a DPS drawing area that automatically manages
issues such as scrolling, scaling, client-side backing store,
incremental redisplay, <it/etc./ The <it/Font Selection Box/, and its
associated <it/Font Preview/, present a convenient and powerful
interface for choosing scalable fonts.  Finally, the <it/Color Picker/
presents an interface for choosing colours using either of the RGB or
HSV spaces.  The latter three widgets are documented in [DPTX]; some
summary Scrolling Widget documentation is available in the <tt/doc/
subdirectory of the <tt/DPS.tar.gz/ file, available from <url
url="ftp://dps.sourceforge.net/pub/dps/DPS.tar.gz">.

The source code for <tt/libdpstkXm/ is included with XFree86; however,
as it depends on Motif, this library is not built by default.
A GTK-based library providing some of the functionality of
<tt/libdpstkXm/ is available from
<url url="http://www.gyve.org/gtkDPS/"
     name="the gtkDPS site">.

<sect2>Libdps and Xt

<p>In X11R5, <tt/libdps/ did not depend on <tt/libXt/.  In X11R6,
however, code was added to make the Xt main loop dispatch to sundry
code on DPS events; with this addition, all programs that link with
<tt/libdps/ need to link with <tt/libXt/, whether they use Xt or not.

This state of affairs is unfortunately true of the version of
<tt/libdps/ included with XFree86.  We are currently considering
various solutions to this problem (including the use of weak linker
symbols or splitting off the guilty functions into a separate
library).

<sect1>Client-side tools <label id="sec:tools">

<p>In addition to the libraries, the client side of DPS consists of two
utilities.

The <tt/makepsres/ utility is used for managing PostScript resources.
Its basic operation consists in walking recursively a filesystem tree,
noting all resources, and then writing out a ``Unix PostScript
Resources,'' file, basically a directory of all the resources found.
This utility is documented in the <htmlurl name="makepsres(1)"
url="makepsres.1.html"> manual page.

The <tt/pswrap/ utility is a stub generator for PostScript clients.
Roughly speaking, it takes as its input textual PostScript code, and
generates a collection of C functions that transmit that code in
pre-tokenised form to the DPS extension.  <tt/Pswrap/ is documented in
[PSWRAP].

<sect1>Sample clients

<p>XFree86 contains three sample DPS clients, <tt/dpsinfo/,
<tt/dpsexec/ and <tt/texteroids/.  They are documented in their
respective manual pages.

A number of sample clients that depend on Motif are available in <url
url="ftp://dps.sourceforge.net/pub/ftp/DPS.tar.gz">.  Additional
sample clients can be found as part of GtkDPS (see above).

The GNUstep environment can be compiled to use DPS for
all rendering; for more information, please see
<url url="http://www.gnustep.org" name="the GNUstep site">.

<sect>The DPS server side <label id="sec:server-side">

<p>In order to use DPS clients, you need to install a DPS server side,
which can be either a server extension (a ``DPS/X extension''), or a
separate process (referred to, variously, either as a ``DPS/NX agent''
or, rather confusingly, as ``Client-Side DPS'' (CSDPS).

<sect1>Display Ghostscript

<p>Display Ghostscript (note the capitalisation), or DGS, is a
client-side implementation of DPS based on the Ghostscript
PostScript interpreter.  DGS is still in beta at the time of writing;
it does, however, provide a very usable implementation of DPS,
although it still has some problems with the semantics of multiple DPS
contexts.

DGS is available from
<url url="http://www.gnustep.org/resources/sources.html"
     name="the GNUstep download area">.

<sect1>The DPS extension

<p>The DPS extension is a much younger project aiming at producing an
efficient server-side implementation of DPS.  The extension is
currently in a state best described as alpha; current versions are
known to crash the X server under some circumstances.

The DPS extension is available from
<url url="http://dps.sourceforge.net" name="the DPS extension site">.

<sect>References

<p>Links to electronic versions of all of these, and more, are
available from <url url="http://dps.sourceforge.net" name="the DPS
extension site">.

[PLRM2] PostScript language reference manual. Adobe Systems, 2nd ed. Addison-Wesley, 1990. ISBN 0-201-18127-4. 

[PLRM] PostScript language reference. Adobe Systems Incorporated, 3rd
ed. Addison-Wesley, 1999. ISBN 0-201-37922-8.

[INTRO] Display PostScript System. Introduction: Perspective for
Software Developers. 15 April 1993.

[CLRM] Display PostScript System. Client Library Reference Manual. 15
April 1993.

[CLSX] Display PostScript System. Client Library Supplement for X. 15
April 1993.

[DPTX] Display PostScript System. Display PostScript Toolkit for X. 15
April 1993.

[PSWRAP] Display PostScript System. pswrap Reference Manual. 15 April
1993.

</article>
