MAIN

Every C program has a main() function — the first function that is called when the program is executed. The typical GIMP plug-in's main function is, in its entirety, as follows:

	MAIN()
      

MAIN is a macro, defined in libgimp/gimp.h, which calls a gimp_main function, which in turn does all sorts of neat stuff. It tries to make sure the plug-in is being called by GIMP, sets up some signal handling, sets up communication between the plug-in and GIMP, and queries the plug-in if need be.

GIMP queries plug-ins on start-up, and it expects them to register themselves in the procedural database (PDB). But how does GIMP know what function to call when it queries? It checks the value of the global variable PLUG_IN_INFO, of type GimpPlugInInfo. From gimp.h:

typedef void (* GimpInitProc)  (void);
typedef void (* GimpQuitProc)  (void);
typedef void (* GimpQueryProc) (void);
typedef void (* GimpRunProc)   (gchar      *name,
                                gint        nparams,
                                GimpParam  *param,
                                gint       *nreturn_vals,
                                GimpParam **return_vals);

struct _GimpPlugInInfo
{
  /* called when the gimp application initially starts up */
  GimpInitProc  init_proc;

  /* called when the gimp application exits */
  GimpQuitProc  quit_proc;

  /* called by the gimp so that the plug-in can inform the
   *  gimp of what it does. (ie. installing a procedure database
   *  procedure).
   */
  GimpQueryProc query_proc;

  /* called to run a procedure the plug-in installed in the
   *  procedure database.
   */
  GimpRunProc   run_proc;
};

So PLUG_IN_INFO consists of pointers to four functions. The first two are ran when GIMP starts and exits, not commonly used among the plug-ins, and so are usually set to NULL. The third is the query function, which many plug-in authors have chosen to name query(). The fourth is called when the plug-in's procedure is to be run, and is, surprisingly enough, often called run(). An example:

/* Function prototypes */
static void query (void);
static void run (gchar      *name,
		 gint        nparams,
		 GimpParam  *param,
		 gint       *nreturn_vals,
		 GimpParam **return_vals);

/* Setting PLUG_IN_INFO */
GimpPlugInInfo PLUG_IN_INFO =
{
  NULL,    /* init_proc */
  NULL,    /* quit_proc */
  query,   /* query_proc */
  run,     /* run_proc */
};

The Query Procedure

As mentioned, GIMP expects plug-ins to register themselves in the PDB when they're queried. This is done through gimp_install_procedure (again, from gimp.h):

Parameters name through date should be fairly self-explanatory. On the rest, I'll make some comment:

struct _GimpParamDef
{
  GimpPDBArgType  type;
  gchar          *name;
  gchar          *description;
};
	    

static GParamDef params[] =
  {
    { GIMP_PDB_INT32, "run_mode", "Interactive, non-interactive" },
    { GIMP_PDB_IMAGE, "image_id", "(unused)" },
    { GIMP_PDB_DRAWABLE, "drawable_id", "Drawable to draw on" },
    { GIMP_PDB_COLOR, "fgcolor",  "Color to draw with"}
  }
	  

The Run Procedure

/* called to run a procedure the plug-in installed in the
 *  procedure database.
 */
typedef void (* GimpRunProc)   (gchar      *name,
                                gint        nparams,
                                GimpParam  *param,
                                gint       *nreturn_vals,
                                GimpParam **return_vals);
	

The run procedure is where the action begins. Its responsibilities include making sure the plug-in was called correctly and setting return values, as well as making sure that your plug-in does whatever it is that it's supposed to do.

struct _GimpParam
{
  GimpPDBArgType type;
  GimpParamData  data;
};
	  

union _GimpParamData
{
  gint32            d_int32;
  gint16            d_int16;
  gint8             d_int8;
  gdouble           d_float;
  gchar            *d_string;
  gint32           *d_int32array;
  gint16           *d_int16array;
  gint8            *d_int8array;
  gdouble          *d_floatarray;
  gchar           **d_stringarray;
  GimpParamColor    d_color;
  GimpParamRegion   d_region;
  gint32            d_display;
  gint32            d_image;
  gint32            d_layer;
  gint32            d_layer_mask;
  gint32            d_channel;
  gint32            d_drawable;
  gint32            d_selection;
  gint32            d_boundary;
  gint32            d_path;
  gint32            d_unit;
  GimpParasite      d_parasite;
  gint32            d_tattoo;
  gint32            d_status;
};
	  

Review

What every plug-in needs:

1. #include <libgimp/gimp.h>

2. PLUG_IN_INFO

3. MAIN

4. A query function, with a call to gimp_install_procedure.

5. A run function, setting a status code return value.

Run: More details

We've said what's required. Now, what's a good idea? This section previously contained some well-intentioned practical advise on how to implement what you just learned, but it was so terribly written that I can't bear to bring it back. So for learning about implementations, I'm afraid you'll be much better off reading source code until this gets re-written.

Move on to the next section to learn more things…