JGimp for Film GIMP README
==========================

PLEASE NOTE: THIS LATEST VERSION HAS NOT YET BEEN UPDATED FOR FILM GIMP.
IT WILL NOT WORK! Use the latest version marked for Film Gimp (0.7.1) if
you desperately need Java support for Film Gimp. However, note that the
API just underwent dramatic changes, and is not backward compatible with
this version.

Note that right now, if you are interested in using JGimp
for Film GIMP, the build/installation process is not yet
completely automated. Patches are appreciated to help out
with this. Send them to: mterry@cc.gatech.edu

Contents:
- Compiling and installing
- Progamming JGimp for Film GIMP
- Known incompatibilities with Film GIMP
- Contact information

Compiling and installing
========================
This version of JGimp requires Java 1.4 and Linux.

To compile this version of JGimp, you need to build it in the filmgimp
source tree. This requires applying a patch and copying some files.
The patch fixes a bug in libgimp/gimp.c and adds the appropriate code,
files, and directories to build JGimp within filmgimp's source tree.
(If someone would like to write a stand-alone Makefile/configure
script for this process, I would gladly switch to that over building
in the source tree. However, this way was the quickest to get JGimp
ported to Film GIMP.)

Follow these steps:

1. Change into the top-level directory of the filmgimp
   source tree:

   cd /path-to-film-gimp-source/filmgimp-0.13

2. Apply the filmgimp-0.13_jgimp.patch included in the top-level
   directory of JGimp:

   patch -p1 < /path-to-the-patch/filmgimp-0.13_jgimp.patch

   If all goes well, it will patch a bunch of files without complaint.

3. cd to plug-ins/jgimp

4. In plug-ins/jgimp, you need to copy the source code and java source
   directory of JGimp into this directory. You must NOT copy the
   Makefile.in from that directory to the filmgimp's plug-ins/jgimp
   directory. Make the following copy:

   cp -R /path-to-jgimp/src/*[ch] /path-to-jgimp/src/java .

5. cd back to the top-level directory:

   cd ../..

6. Re-run configure, adding a flag to tell it where to find java. This
   should be the top-level directory of the Java installation (not its
   bin directory):

   ./configure --prefix=/install-film-gimp-here \
   --with-jdk-prefix=/path/to/java

7. Type:

   make
   make install

   And that should compile and install the JGimp plug-in and its
   Java-based plug-ins.

8. Run Film GIMP. Open any image. Right-click on the image, and you
   should see an entry in Filters called
   Filters->Digital Cameras->Nikon Image Divider

   This will take the selected drawable, carve it up into a 4x4 grid,
   and put each square in its own layer in a new image.

   For 8-bit RGB images, there is also a desaturation plug-in written
   in Java, with a Swing-based dialog. In Filters->Colors->Desaturation Tools
   you'll see a list of desaturation commonds, based on the desaturate.jar
   plug-in. If you run the Desaturation Dialog... command, a Java-based dialog
   will pop up for desaturating the active drawable.


Progamming JGimp for Film GIMP
==============================

See README.java_plugins for pointers about the process of writing a
plug-in for JGimp.

JGimp is a light wrapper on the C-API for the GIMP. It
provides a few basic hooks into the GIMP:

1. The ability to call any PDB procedure
2. The ability to install plug-ins and extensions to
   the GIMP
3. The ability to read and write pixels

Hooks 1 and 2 are bit-depth independent, meaning that the
bytes-per-pixel depth of images should not affect their functionality
at all. However, scripts written in Java will of course be dependent
upon which functions are available in the PDB. Thus, if you are
concerned about writing plug-ins that work with GIMP 1.2.x and Film
GIMP, you will need to make sure that the PDB functions called are
present in both versions.

Hook 3 is bit-depth dependent. JGimp has several "read/write" pixel
methods, broken down into two broad categories: those that consider
the pixel data "raw" data (eg., readPixelRegionInNativeByteFormat),
and those that convert it to a Java-friendly format (eg.,
readPixelRegionInJavaIntFormat). All of the methods that read in
Native format will work with images of any bit-depth (though this has
not been extensively tested). The reason they work is because JGimp
simply performs a raw copy from the GIMP pixel region into the array
passed to the function. Thus, if you have an image represented by,
say, 16-bit Floats, you will get that data back in raw bytes, and will
need to interpret it in Java if you want to manipulate individual
pixels.  The methods that read in Java-friendly format (that is, that
translate them into a standardized Java format) will only work with
images up to 8-bits. However, if there is sufficient demand, it should
not be difficult to provide similar support for greater bit depths
in Java-friendly formats.

For more information and specifics about how pixel read/writes are
performed, read the javadocs for JGimpProxy
(org/gimp/jgimp/proxy/JGimpProxy.java).

Known incompatibilities/bugs with Film GIMP
======================================
There are a number of utility classes that require certain PDB functions, not
all of which are present in Film GIMP.  For example, JGimpImagePanel, a
class which can render a specific drawable in a JPanel, does not work with
image depths >8 bits. It may also call some PDB functions not available in Film
GIMP. However, as described above, the primary functions in JGimpProxy should
all work as documented, keeping in mind that the read/write pixel functions do
not work at bit depths greater than 8.

Currently, Film GIMP does not always shutdown cleanly when running JGimp...

Contact information
===================
If you have a question that is not answered by the docs or code, you can
send a question to our discussion list:
 jgimp-developers@lists.sourceforge.net
