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

<article>

<title>X and DPS
<author>Juliusz Chroboczek, <email/jch@pps.jussieu.fr/
<date>27 February 2001, updated 08 May 2005</date>

<ident>
Updated by Jim Gettys.
$Id: dps.sgml,v 1.4 2005/05/08 22:19:32 alanc Exp $
</ident>

<toc>

<sect>Notice of Obsolence and Planned Removal from X.Org Releases

<p> Note that DPS is now obsolete.
<p>
At the time when I started this project, there was no decent rendering interface for X11 other than DPS.
<p>
Since then, there has been a large amount of work on a simple and clean X server extension, Xrender, which provides the basis for just such an interface.
<p>
Rendering libraries that are being built above Xrender include Xft, 
a font rendering library built on FreeType; 
Cairo, a geometry rendering library that provides PostScript-like 
rendering primitives but with intrinsic support for Porter-Duff 
compositing (transparency); Pango, a high-level typesetting library. 
<p>
If your application uses DPS, please consider porting it to the above libraries.
See <url url="http://dps.sourceforge.net" name="the DPS extension site">
for more details
<p>
The DPS software is included and built by default (except as noted below)
in the X.Org X11R6.8 release series.   The software will be included, but
not built unless specifically configured by the builder, in the X.Org 
X11R6.9 release series.   At this time, X.Org does not plan to include any
of the DPS software in X11R7.0 or later releases.

<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
X11R&relvers;.  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 X11R&relvers;;
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 X11R&relvers;.

<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 X11R&relvers;; 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 X11R&relvers;.  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>X11R&relvers; 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>
