README

   1 IJS 0.35
   2
   3 News as of 0.35:
   4 11 Feb 2004
   5
   6 The autoconf build system has been moderized and we now use
   7 libtool for portable shared library building. Thanks to Roger
   8 Leigh for helping with that.
   9
  10 Also a bug with ColorSpace field was corrected, thanks to David
  11 Suffield.
  12
  13 News as of 0.34:
  14 22 Apr 2002
  15
  16 The source files now have official MIT license banners. Thanks to
  17 www.opensource.org for hosting the ur-text of this license. Also
  18 some clarifications on namespace management in the spec.
  19
  20 There is now an IJS website, graciously hosted by linuxprinting.org.
  21 http://www.linuxprinting.org/ijs/
  22
  23 There have been some minor improvements in the makefile.
  24
  25 News as of 0.33:
  26
  27 The buffer size has been increased to 4096. It should probably be
  28 dynamically allocated, though. Minor clarification in BitsPerSample
  29 language in spec (thanks to Jackie Chang for pointing out the
  30 ambiguity).
  31
  32 News as of 0.32:
  33
  34 The xres and yres fields of ph are now floats.
  35
  36 The example server now supports margins. A few small bugs have
  37 been cleaned up as well.
  38
  39 News as of 0.31:
  40
  41 A number of small cleanups in the code. The example client and server
  42 support more querying and enumeration, but not yet margins.
  43
  44 There is a new API for the client to query the negotiated version
  45 number.
  46
  47 The ijs_exec_unix module now sets the SIGPIPE signal to ignore. This
  48 way, if the client abnormally exits, it allows the error to propagate
  49 through the read() or write() call to the pipe, rather than
  50 immediately killing the client.
  51
  52 News as of 0.30:
  53
  54 It now builds as a library. Also, there is basic autoconf support (but
  55 not automake or libtool). It's probably best to link the static
  56 library for now. I'm open to suggestions - I'm open to drinking the
  57 entire pitcher of auto* Kool-Aid, but we probably won't use libtool
  58 in Ghostscript builds.
  59
  60 This release fixes a number of bugs and improves portability. In
  61 particular, server errors should now bubble up to the client, and
  62 the termination logic has been patched according to David Suffield,
  63 who discovered a race condition there. Thanks to David and Russell
  64 for patches.
  65
  66 The spec is now in a reasonable draft. See ijs_spec.sgml and
  67 ijs_spec.pdf. Comments and suggestions are welcome.
  68
  69 The example client and server have _not_ yet been updated to use
  70 the newer features of the ijs spec. Patches are welcome.
  71
  72 News as of 0.29:
  73
  74 I've added a number of things discussed on the mailing list, including
  75 listing and enumerating parameters, as well as a job abstraction.
  76 The client interface has changed a bit - job id's are now present
  77 in most callbacks, colorspace is now presented only as a string, and
  78 there are quite a few more callbacks.
  79
  80 I've started a skeleton of a protocol spec in DocBook.
  81
  82 Note, there's a potential race condition in EXIT noted by David
  83 Suffield. The fix hasn't yet been merged in from his work.
  84
  85 News as of 0.2:
  86
  87 This version integrates set_param and get_param, and has moved the
  88 "page header" processing to use set_param.
  89
  90 Also, there are both Windows (MS VC++) and Unix makefiles. Use
  91 "make -f unix.mak" to build on Unix. Thanks to Russell Lang for
  92 Windows portability work.
  93
  94
  95 Introduction
  96
  97 This is an early snapshot of IJS. I expect the protocols and API's to
  98 evolve somewhat, and things like error handling are still far from
  99 perfect. However, I'm pretty happy that this is going in the right
 100 direction.
 101
 102 I am doing this prerelease so that authors of various packages related
 103 to raster-based printing can start thinking about how to integrate it.
 104 Ideally, all producers of printable raster data should be able to
 105 function as an ijs client, and all consumers should be able to
 106 function as an ijs server. This release is about as functional as
 107 piping pnm's, which is primitive, but the way a lot of drivers still
 108 work.
 109
 110
 111 What is IJS?
 112
 113 IJS is, first and foremost, a protocol for transmission of raster page
 114 images. This snapshot provides a reference implementation of the
 115 protocol, the design of which is still in flux. When the protocol
 116 specification is published, it will be authoritative. Applications
 117 should feel free to link against the library provided in this package,
 118 adapt that code for their own needs, or roll a completely new
 119 implementation.
 120
 121 The protocol is a fairly traditional client-server design. In general,
 122 the client sends one or more page images to the server, along with
 123 various metadata. Communication is through simple "commands", which
 124 are essentially size-prefixed packets. The client sends a command to
 125 the server, then waits for a response command, either ACK or NAK.
 126
 127 The server "speaks" IJS through stdin and stdout. One consequence of
 128 this design decision is that the server can be invoked remotely, for
 129 example through ssh. It's not clear yet how useful this will be, but
 130 at least people can experiment with it.
 131
 132 Currently, all data goes through the stdin and stdout pipes. It is
 133 envisioned that a shared memory transport will also be provided,
 134 transparently. IJS will fall back to pipes if shared memory is not
 135 available for any reason.
 136
 137 I'm not yet convinced that the performance win for shared memory is
 138 significant. I would like to benchmark domain sockets as well, as they
 139 are likely to provide better performance than pipes, and are also
 140 highly desirable for cases where the server runs as a persistent
 141 daemon.
 142
 143 This tarball provides an "IJS library" in the form of ijs, ijs_client,
 144 and ijs_server. It also provides an example client (capable of reading
 145 pnmraw files) and an example server (capable of generating
 146 PostScript). I imagine that the example programs will be useful for
 147 development and testing, but that end-users probably won't find a need
 148 for them.
 149
 150 To try IJS, compile and run "./ijs_client_example -s
 151 ./ijs_server_example -pOutputFile=/tmp/tmp.ps foo.ppm". This will
 152 invoke ./ijs_server_example, which will in turn generate a /tmp/tmp.ps
 153 file.
 154
 155 The ijs_client_example takes a -p command line argument for setting
 156 parameters, and a -r argument for setting resolution.  Here is a
 157 typical command line:
 158
 159 ./ijs_client_example -s ./ijs_server_example -pOutputFile=/tmp/tmp.ps \
 160   -r300 in.ppm
 161
 162 The syntax of -p is a sequence of key=value pairs, separated by
 163 commas.  A backslash in the value escapes the next character (allowing
 164 embedded commas in the value). Thus, '-pfoo=bar, quux=a\,b' sets the
 165 key "foo" to the value "bar, and the key "quux" to the value "a,b".
 166
 167
 168 FAQ
 169
 170 What does IJS stand for?
 171
 172 It stands for "raster printer driver architecture." It's spelled
 173 U+30EA U+13DA, to avoid confusion, and to save space in UTF-16
 174 encodings.
 175
 176 Actually, the name derives from HPIJS, which presumably stands for HP
 177 InkJet Server. The name pays homage to HPIJS for the inspiration,
 178 while communicating that it's not specific to HP printers.
 179
 180 Licensing
 181
 182 All source code in this distribution is released under the MIT
 183 License. I want everybody to be able to use this.
 184
 185
 186 More stuff to write:
 187
 188 Actual specification for the protocol (in draft).
 189
 190 Client spawns server, invoker invokes client and server, and
 191 persistent server daemon modes.
 192
 193 Negotation of extensions (goal is interoperability between versions).
 194 (Actually, the PING/PONG protocol as it exists negotiates version
 195 numbers).
 196
 197 TODO:
 198
 199 Shared memory transport.
 200
 201 Should have an alternate mode in which the client is passed the pipe
 202 information, rather than having to spawn the server.
 203
 204 wait() cleanup of invoked server.
 205
 206 Package library up as libijs.a, .so (partially done)