User Filter Plug-in for The Gimp
================================

Q: What does this plug-in do ?

A: This plug-in will enable you to use filters generated with
   Photoshop Filter Factory. These filters come in various
   file formats: text (.txt, .ffl, .afs) and binary (.8bf).
   There is a catch, however, in the fact that not all .8bf
   files are Filter Factory filters and thus are not under-
   stood by this plug-in.
   You can also write your own Filter Factory style filters
   with this plug-in and share them with users of the original
   Filter Factory.


Q: I already have the Photoshop filter interface plug-in pspi
   installed. So what is this plug-in good for then ?

A: The pspi plug-in will also be able to utilize the .8bf plug-ins
   generated by Filter Factory. But it has its drawbacks, since
   (a) the initialization takes up a lot time, (b) the menu gets
   clustered with filters (if you have quite some), and (c) every
   Filter Factory binary plug-in is at least 48K in size - for the
   "Andrew's Filters" collection this sums up to about 58M on your
   disc whereas the same collection as .guf will take only about
   1500K.
   Furthermore, there are also people who are not working on x86
   based machines.  They would not be able to run pspi - but they
   can use this plug-in whatsoever.
   Filter Factory binary filters have also no means of localization.
   When you import those filters in User Filter, however, they can
   be localized by adding the locale data for the control tags that
   are defined by the filter.  In addition, you also get a filter
   description (which is used as a tooltip in the Gimp's menu) and
   tooltips for the filter controls (all of which also can easily be
   adopted to the current locale).
   You can also translate the filters into native code Gimp plug-ins
   using the uf2c(1) tool.  The size of the binary (with statically
   linked userfilter library) will then be somewhat smaller than a
   Filter Factory .8bf file.  It will also execute faster than the
   same filter run by the byte-code interpreter of User Filter.


Q: But I like the idea of being able to access the filters from the
   filters menu of the image.

A: You can also do that with User Filter. In the Filter Manager
   dialog of the plug-in, you can select (or deselect) the filters
   you want in your Gimp menu (you will have to restart Gimp though,
   to take those changes into effect).  You are still able to access
   any other filter through the manager panel or directly load them
   from the editor panel of the plug-in.
   The filters need to be in a writable directory though to make this
   happen (i.e. you won't be able to change the settings for filters
   in a system-wide data directory or in the data directory of another
   user).
   You can also translate the filter descriptions into native code
   plug-ins for the Gimp using uf2c(1).  These will also install in
   the Gimp's menu once you've moved them into your plug-in directory.
   You need to make sure, however, that for the filter to be used in
   the stand-alone mode or as a binary plug-in, the "Category" of the
   filter needs to be set to a correct Gimp menu path.


Q: I checked the "Plug-in" column of a filter in the manager panel,
   but the filter does not show up in the Gimp's menu, even when I
   re-start the program.

A: You need to set a correct menu path for the filter in the "Category"
   entry of the editor panel.  If you fail to comply, The Gimp cannot
   install the filter in its menu.


Q: I understand that the formulas for the filters get interpreted
   by the plug-in for every pixel in the image. This must be very slow.
   The .8bf Filter Factory  plug-ins are surely quicker, because they
   are Windows executables, even if they load slower with pspi.

A: The .8bf Filter Factory binary plug-ins do just the same as this
   plug-in: they first byte-compile the formulas and then interpret
   the byte-compiled code.


Q: I understand that the original userfilter just worked on .8bf,
   .txt, .afs, and .ffl files.  Why is there another file format now
   and what is it good for ?

A: The original file formats are a mess.  They are unstructured and
   awful to parse.  You can also damage them by editing the text
   format files in a normal text editor program, because this could
   destroy the way the end-of-line is handled in the files (some are
   formatted in the Mac way, others as DOS text etc.) which is
   important for the file load routines.
   Last, but not least, it is not possible to expand those formats.
   User Filter is not Filter Factory (although it might act like it
   and can understand its files).  It already has a number of features
   that cannot be stored in the old file formats (e.g. a meta descrip-
   tion of what a filter does, the tooltips, or the locale data), but
   which are of interest to The Gimp.  Also, future extensions (like
   new functions, mathematical constants etc.) cannot be handled by the
   old files, since there is no way to check the compatibility of a
   filter with the version of the plug-in that is in use.  The new file
   format has a feature version information tag that is used for this
   purpose.


Q: I have used User Filter in the past with Gimp v1.x.x - now I cannot
   find the tons of filters that used to work with it although I have
   installed them correctly in the userfilter data directory.

A: Things have changed.  The original file formats were a mess and
   induced several bugs.  It has therefore been decided that the plug-
   in will only accept its new native file format as a proper filter
   description when looking for (new) filters in its data directories.
   You can still import the old filters (in the editor panel) or convert
   them with one of the command line utilities (8bf2guf(1), afs2guf(1),
   ffl2guf(1), and txt2guf(1)).


Q: But it is soooo slow - this is not usable for my monster size images.

A: Actually, it is quite fast - about 30% faster than the original (v0.8)
   plug-in - but since the byte code compiler can do only little optimi-
   zation, speed of the filter still depends highly upon the quality of
   the code written and the complexity of the formula.
   To get around this, there is a converter uf2c(1) which will produce
   a C source for a standalone GIMP plug-in from a filter description.
   This source can then be translated with an optimizing C compiler
   using gimptool(1) and put in the GIMP plug-ins directory.
<future-version>
   For your convenience, there is also a wrapper uftool(1) that automates
   this process (translate filter into C, apply gimptool) for you.
   A standalone plug-in produced by this tool should be significantly
   faster (although not quite as fast as a plug-in hand-written in C)
   than the byte-compiled filter.
</future-version>


Q: I have translated a filter with uf2c(1).  Now, I want to extend it (add
   funtionality and/or locale data), but I seem to have lost the original
   filter file.  Is there a way to decompile a plug-in created with uf2c ?

A: Yes and no.  There is no way to decompile a plug-in created with an op-
   timizing C compiler (which is what you did).  However, the filter code
   is still in the binary (it is needed for the control value presets, the
   labels / tooltips, and locale data; the formulas are not needed, but
   small enough to keep, so their extra payload does not really enlarge the
   memory footprint of a compiled plug-in significantly).  You will be able
   to extract this data using the strings(1) command or your favourite data
   dumper.


Q: I downloaded a FF filter from the internet and it does not work.

A: Some FF filters use undocumented features (I have seen some using
   a value "t" for instance, which does not show up in the FF docu-
   mentation).  Others include invalid characters in the code portion
   of the filter which might confuse the parser.
   If you happen to have a filter that results in syntax errors, it
   is most likely that it is because of one of the two reasons stated
   above.  You then can correct the formula in the editor panel and
   save the corrected filter.
   If else the formulas compile alright but the filter does not work
   as expected, it is probably a bug in the code generator or the
   optimizer of User Filter treats.  This should be, however, least to
   be expected.
