$Id: README,v 6.0 2001/06/19 08:22:18 sgifford Exp $

gnome-print-filter is a library for dealing with PostScript encoding
filters in a way similar to how the PostScript language itself deals
with them.

It is Copyright (c) 2001 by Scott Gifford, and is distributed under
the terms of the GNU Library General Public License (version 2 or
later).  See the included file COPYING.LIB for more information about your
rights when using this software, and your responsibilities when
distributing modified versions.

It was written by Scott Gifford <sgifford@tir.com>, based on the
filter code from gnome-print (by Chema Celorio <chema@celorio.com>)
and from the Perl module Text::PDF::Filter (by Martin Hosken
<Martin_Hosken@sil.org>).  While they deserve some of the credit for
this good parts of this library, they deserve none of the blame for
the bad parts.  They may or may not know that this package even
exists, so please don't email them with questions.

==========================
==     gnome-print      ==
==========================
To use gnome-print-filter with gnome-print:

  1. Get the 1-4-branch branch of gnome-print CVS.

  2. Download the "gnome-print-filter.tar.gz" package.  

  3. Go into the gnome-print CVS directory, or a copy of it you are
     working on.  All other actions will need to take place from
     inside this directory.  For example:

         $ cd ~/src/CVS/gnome-print

  3. Untar "gnome-print-filter.tar.gz" from inside the gnome-print
     directory.  For example:

         $ tar xvzf ~/downloads/gnome-print-filter.tar.gz

  4. Still in the gnome-print directory, apply
     gnome-print-filter.patch.  For example:

         $ patch -p1 <gnome-print-filter.patch

  5. Clean up the old filter code:

         $ rm -f libgnomeprint/filter*

  5. Still in the gnome-print directory, run "automake" and "autoconf"
     to rebuild configure and friends with the patches applied:

         $ automake
         $ autoconf

     If you get any errors, something didn't go right.

  6. Still in the gnome-print directory, run ./configure and make to
     build gnome-print:

         $ ./configure; make

  7. Test the filter code.  The gnome-print-filter contains a complete
     test suite; since it is still experimental code, you should run
     the tests to make sure that everything is working properly.  The
     tests will take 5-10 minutes depending on your computer.  If
     you're impatient and only want to wait about a minute, run
     "quicktest" instead of "bigtest" below.  To compile and run the
     tests:

         $ cd tests
         $ make
         $ cd filters
         $ ./bigtest
         $ cd ../..

     If you get any errors, something has gone wrong, and things
     aren't likely to work properly.

  8. Test gnome-print.  gnome-print comes with some test programs of
     its own.  Not everything can be tested before gnome-print is
     fully installed, but it's better than nothing.  gnome-print's
     tests are located in the "tests" subdirectory, and produce output
     in the form of a PostScript file or a printed page.  If you
     followed the previous step, these test programs are already
     compiled; run them from tests by typing:

         $ cd tests
         $ ./testprint 
         $ gv /path/to/output.ps
         $ cd ..

     Other tests can be run by typing "testprint1", "testprint2",
     etc. instead of "testprint" above.

  9. Install and enjoy!

         $ make install

Current Issues:

  * Only images are encoded, and only when written to PostScript.

  * Only a RunLengthEncode+ASCII85Encode filter is supported.

Comments:

  * I don't know enough about the configuration of gnome-print to know
    how to infer what an appropriate set of drivers are.  Things I'd
    need to know are:

    - Language level supported (1 can only use ASCIIHexEncode,
                                2 supports ASCII85Encode and 
                                  RunLengthEncode,
                                3 supports FlateEncode (not yet 
                                  implemented)
                               )

    - Whether it can handle 8-bit input.  GhostScript has no problem
      with 8-bit input, so we're wasting 25% of space by
      ASCII85Encoding binary data.

    - Possibly more specific information about what filters are
      supported.

  * I've tried to write this library in a way that is easily
    extensible, and that lends itself to external dymanic modules.
    Hopefully those will be implemented someday, by me or by somebody
    else.
 

==========================
==        Using         ==
==========================

For a concrete example of how to use the filter library, see the
program "filtertest" included with the distribution.

filter_register_all
-----
int filter_register_all();

To begin using the filter library, #include "filter.h" in your
program, and somewhere before making any other filter-related calls, call
the function "filter_register_all()".  This will register all filter
functions compiled in.  For example:

    if (filter_register_all() != 0)
    {
      fprintf(stderr,"Whoops!  Error in filter_register_all: %s\n",strerror(errno));
      exit(1);
    }

filter_register_all returns 0 if it succeeds, and -1 if it doesn't.
It makes some effort to set errno if it fails.

filter_init
-----
Filter *filter_init(char *filter_name);

Once you have done that, you can create a new filter with the
filter_init() function.  It takes a single paramater, the name of the
filter you'd like to initialize, and returns a filter handle (Filter
*).  If the filter cannot be created, NULL is returned.  For example:

   Filter *filt;

    if ((filt = filter_init(filtername)) == NULL)
    {
      fprintf(stderr,"Whoops!  Error in filter_init: %s\n",strerror(errno));
      exit(1);
    }

Each filter supports a single transformation, with one exception.  The
"multi" filter allows additional filters to be chained together by
setting options.

filter_opt_set*
-----
int filter_opt_setstr(Filter *filt, char *opt, char *value);
int filter_opt_setptr(Filter *filt, char *opt, void *value);
int filter_opt_setint(Filter *filt, char *opt, long value);

To set options for a filter, use the filter_opt_setstr,
filter_opt_setptr, and filter_opt_setint functions.  Each takes as
parameters the filter the option should be set for, the name of the
option to be set, and the value for the option.  0 is returned if
everything works out, -1 if it doesn.t  For example:

    if (filter_opt_setstr(filt,"add","RunLengthEncode") != 0)
    {
      fprintf(stderr,"Whoops!  Error setting option: %s\n",strerror(errno));
    }

    Filter *some_other_filter;
    [ ... ]
    if (filter_opt_setptr(filt,"add", some_other_filter) != 0)
    {
      fprintf(stderr,"Whoops!  Error setting option: %s\n",strerror(errno));
    }
    
filter_opt_setint is currently unimplemented, since no filters use
it.  Options for particular filters are documented in their individual
section below, but it would only be fair to warn you that the only
driver with any options at all is "multi".

filter
------
int filter(Filter *filt, int final, int inbytes, char *inbuf, int *outbytes, char **outbuf);

A filter is used by passing in a chunk of input, and reading out the
chunk of output sent back.  It's important to realize that there is
not necessarily any relationship between the amount of data input and
the amount of data output, and that some filters (particularly
RunLengthEncode) tend to return no data at all if you're in the middle
of a fairly large compression run.  filter() takes as parameters the
filter that should process the data a boolean value "final" that
indicates whether or not this is the last chunk through the filter,
and any data in internal buffers should be flushed; an integer value
"inbytes" with the number of bytes being sent in; a pointer "inbuf" to
a buffer containing said bytes; a pointer "outbytes" to an integer
where filter() will store the number of output bytes generated; and a
pointer "outbuf" to a pointer to a buffer where filter() will put the
address of the buffer actually containing the output bytes.
Confusing, huh?  An example will help:

    Filter *filter;      /* Filter we're using */
    int final;           /* Boolean flag -- are we on the last pass? */
    char buf[8192];      /* Input buffer */
    int bufsize = 8192;  /* Input buffer size */
    int nread;           /* Return value from fread() */
    int outsize;         /* Hold return value from filter() */
    char *outbuf;        /* Hold return pointer from filter() */

    [ ... ]

    final = 0;
    while (!final)
    {
      nread=fread(buf, 1, bufsize, stdin);
      if (nread < bufsize)
        final=1;
	if (filter(filt,final,nread,buf,&outsize,&outbuf) != 0)
        {
	  fprintf(stderr,"Whoops!  Error processing filter: %s\n",strerror(errno));
          exit(1);
        }
      filter(filt,final,nread,buf,&outsize,&outbuf);
      fwrite(outbuf,1,outsize,stdout);
    }

The example reads in a bufferful of bytes with fread(3), decides that
this is the final pass if it was a short read, then calls filter,
passing it the filter (which was created in the elided part of the
program), the final flag, the number of bytes just read (and hence the
number of bytes that filter() should process), the buffer containing
the bytes just read (and that filter should process), a pointer to an
integer where filter() will store the number of bytes returned, and a
pointer to a pointer to a buffer, where filter() will place a pointer
to an internal buffer containing the output data.

All memory management of data which is input to filter is handled by
the caller; all memory management of data which is output from the
filter is stored in internal buffers managed by the filter itself.
filter() will never free or in other ways modify data you send to it,
and you should never try to free or modify any data from the buffers
it sends back.

Each filter tends to allocate for its buffers between 125% and 200% of
the input buffer size.  For chained buffers, each filter in the chain
will reserve that amount of memory.  Additionally, there is some extra
overhead associated with each call to filter(), a tiny bit from the
function calls themselves, and quite a bit more from the extra work
that has to be done to restore state from the Filter* structure, then
store state back in it before returning.  Because of this, the
performance of filter is a typical time/memory tradeoff.  Usually
sending in an entire file at once will consume a bit more memory than
you'd like, and sending a file in one byte at a time will take a bit
longer than you'd like.  Buffer sizes of 1-10K should probably work
best.  8K (8192 bytes) tends to be a good natural boundary, since it
is an even multiple of most operating systems' block sizes.

filter_free
-----
int filter_free(Filter * filt);

Free all memory associated with a filter, and destroy the filter.  If
you want to use the filter again, you'll need to re-create it with
filter_init().  Returns 0 if destruction succeeds and -1 if it
doesn't.  Example:

    if (filter_free(filt) != 0)
    {
      fprintf(stderr,stderr,"Whoops!  filter_free failed: %s\n",strerror(errno));
      exit(1);
    }

==========================
==     The Filters      ==
==========================


ASCIIHexEncode
-----
Availability: PostScript LL 2-3
              As readhexstring in PostScript LL 1
Output size: About 200% of input size
Decode with: ASCIIHexDecode
Options: None

Encode each byte of input data with two hex characters, which together
represent that byte as a base-16 (hexadecimal) number.  ASCII encoding
of some kind is often required by PostScript printers which cannot
handle binary data.  ASCII85Encode is more efficient than this, but is
not supported as part of PostScript language level 1.

See "Filters and Reusable Streams" (PN LPS5603) from Adobe, Sec. 2.1.


ASCII85Encode
-----
Availablity: PostScript LL2-3
Output size: About 125% of input size
Decode with: ASCIIHexDecode
Options: None

Encode each 4 bytes of input data with 5 bytes of output data.  ASCII
encoding of some kind is often required by PostScript printers which
cannot handle binary data.  ASCII85Encode is the most efficient of the
ASCII encoders, but is not supported by PostScript language level 1.

See "Filters and Reusable Streams" (PN LPS5603) from Adobe, Sec. 2.2.


RunLengthEncode
-----
Availability: PostScript LL2-3
Output size: 5%-101% of input size
Decode with: RunLengthDecode
Options: None

Encode long strings of the same binary data as a single 2-byte
sequence.  The penalty paid for this is that long strings of binary
data with no repetition will be slightly larger, about 1%.  Still,
RunLengthEncode will make a good number of input images significantly
smaller, especially for grayscale images and/or images that have large
areas of black or white.

The output of RunLengthEncode is still binary, so if your printer
requires an ASCII encoding, you'll need to use ASCII85Encode (or
ASCIIHexEncode) as well.  See the entry for "multi" later on for
information on chaining these together.

See "Filters and Reusable Streams" (PN LPS5603) from Adobe, Sec. 4.


NullEncode
-----
Availability: PostScript LL2-3
Output size: Exactly the same as input size.
Decode with: No decoding necessary
Options: None

Encode the input file as itself.  This is mostly useful for testing,
or for situations where you thought you were going to need an encoder
but didn't.

Note that PostScript does not define a NullDecode filter.

See "Filters and Reusable Streams" (PN LPS5603) from Adobe, Sec. 6.

multi
-----
Avalability: No direct PostScript equivalent
Output size: Product of all chained filters
Decode with: Inverted chain of decode filters
Options: add

The multi filter lets you chain an arbitrary number of filters
together, which the output of each one acting as the input the the
next, and the final output returned to the caller.  In a PostScript
program, chaining together of filters is straightforward:

    currentfile
     /ASCII85Decode filter
     /RunLengthDecode filter

C is not so forgiving.

To append another filter onto a multi, use the add option.  You can
use filter_opt_setstr() to create a filter by name, or you can append
an actual Filter* object with filter_opt_setptr().  You'll need to use
the latter method if you want to set any options for the filters
you're chaining together.


==========================
==   Writing a Filter   ==
==========================

A filter is implemented as a Filter structure, which contains the
filter's name, pointers to different functions for the filter, and a
pointer to internal data for each filter instance.

To create a new filter, define a filter_init() function which creates
the filter, define any functions that your filter will need (at least
a filter() function), and register your filter in filter_register_all.

All of the filters included with this package are good examples.
Probably filter_hexenc.c is the best example, since the code itself is
very straightforward.  filter_rle.c has an example of keeping some
more complex state between calls to filter(), and filter_null is about
as simple as a working filter can possibly be.