gimp

## gimp gimp — Main functions needed for building a GIMP plug-in. This header includes all other GIMP Library headers. |

## Synopsis

    #define     GIMPVAR
    gchar*      gimp_version                    (void);
    extern      const guint gimp_major_version;
    extern      const guint gimp_minor_version;
    extern      const guint gimp_micro_version;
    #define     gimp_get_data
    #define     gimp_get_data_size
    #define     gimp_set_data
    void        (*GimpInitProc)                 (void);
    void        (*GimpQuitProc)                 (void);
    void        (*GimpQueryProc)                (void);
    void        (*GimpRunProc)                  (const gchar *name,
                                                 gint n_params,
                                                 const GimpParam *param,
                                                 gint *n_return_vals,
                                                 GimpParam **return_vals);
                GimpPlugInInfo;
                GimpParamDef;
                GimpParamRegion;
    union       GimpParamData;
                GimpParam;
    #define     MAIN                            ()
    gint        gimp_main                       (const GimpPlugInInfo *info,
                                                 gint argc,
                                                 gchar *argv[]);
    void        gimp_quit                       (void);
    void        gimp_install_procedure          (const gchar *name,
                                                 const gchar *blurb,
                                                 const gchar *help,
                                                 const gchar *author,
                                                 const gchar *copyright,
                                                 const gchar *date,
                                                 const gchar *menu_label,
                                                 const gchar *image_types,
                                                 GimpPDBProcType type,
                                                 gint n_params,
                                                 gint n_return_vals,
                                                 const GimpParamDef *params,
                                                 const GimpParamDef *return_vals);
    void        gimp_install_temp_proc          (const gchar *name,
                                                 const gchar *blurb,
                                                 const gchar *help,
                                                 const gchar *author,
                                                 const gchar *copyright,
                                                 const gchar *date,
                                                 const gchar *menu_label,
                                                 const gchar *image_types,
                                                 GimpPDBProcType type,
                                                 gint n_params,
                                                 gint n_return_vals,
                                                 const GimpParamDef *params,
                                                 const GimpParamDef *return_vals,
                                                 GimpRunProc run_proc);
    void        gimp_uninstall_temp_proc        (const gchar *name);
    GimpParam*  gimp_run_procedure              (const gchar *name,
                                                 gint *n_return_vals,
                                                 ...);
    GimpParam*  gimp_run_procedure2             (const gchar *name,
                                                 gint *n_return_vals,
                                                 gint n_params,
                                                 const GimpParam *params);
    void        gimp_destroy_params             (GimpParam *params,
                                                 gint n_params);
    void        gimp_destroy_paramdefs          (GimpParamDef *paramdefs,
                                                 gint n_params);
    guint       gimp_tile_width                 (void);
    guint       gimp_tile_height                (void);
    gint        gimp_shm_ID                     (void);
    guchar*     gimp_shm_addr                   (void);
    gdouble     gimp_gamma                      (void);
    gboolean    gimp_install_cmap               (void);
    gint        gimp_min_colors                 (void);
    gboolean    gimp_show_tool_tips             (void);
    gboolean    gimp_show_help_button           (void);
    GimpCheckSize gimp_check_size               (void);
    GimpCheckType gimp_check_type               (void);
    gint32      gimp_default_display            (void);
    const gchar* gimp_wm_class                  (void);
    const gchar* gimp_display_name              (void);
    gint        gimp_monitor_number             (void);
    const gchar* gimp_get_progname              (void);
    void        gimp_extension_enable           (void);
    void        gimp_extension_ack              (void);
    void        gimp_extension_process          (guint timeout);
    GimpParasite* gimp_parasite_find            (const gchar *name);
    gboolean    gimp_parasite_list              (gint *num_parasites,
                                                 gchar ***parasites);
    gboolean    gimp_parasite_attach            (GimpParasite *parasite);
    gboolean    gimp_parasite_detach            (const gchar *name);
    void        gimp_attach_new_parasite        (const gchar *name,
                                                 gint flags,
                                                 gint size,
                                                 gconstpointer data);

## Description

Main functions needed for building a GIMP plug-in. This header includes all other GIMP Library headers.

## Details

### GIMPVAR

    #define     GIMPVAR

### gimp_version ()

    gchar*      gimp_version                    (void);

Returns the host gimp version.

This procedure returns the version number of the currently running gimp.

Returns : | The gimp version.

### gimp_major_version

    extern const guint gimp_major_version;

### gimp_minor_version

    extern const guint gimp_minor_version;

### gimp_micro_version

    extern const guint gimp_micro_version;

### gimp_get_data

    #define gimp_get_data         gimp_procedural_db_get_data

### gimp_get_data_size

    #define gimp_get_data_size    gimp_procedural_db_get_data_size

Returns : |

### gimp_set_data

    #define gimp_set_data         gimp_procedural_db_set_data

### GimpInitProc ()

    void        (*GimpInitProc)                 (void);

### GimpQuitProc ()

    void        (*GimpQuitProc)                 (void);

### GimpQueryProc ()

    void        (*GimpQueryProc)                (void);

### GimpRunProc ()

    void        (*GimpRunProc)                  (const gchar *name,
                                                 gint n_params,
                                                 const GimpParam *param,
                                                 gint *n_return_vals,
                                                 GimpParam **return_vals);

`name` : |
`n_params` : |
`param` : |
`n_return_vals` : |
`return_vals` : |

### GimpPlugInInfo

    typedef struct {
      /* 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;
    } GimpPlugInInfo;

### GimpParamDef

    typedef struct {
      GimpPDBArgType  type;
      gchar          *name;
      gchar          *description;
    } GimpParamDef;

### GimpParamRegion

    typedef struct {
      gint32 x;
      gint32 y;
      gint32 width;
      gint32 height;
    } GimpParamRegion;

### union GimpParamData

    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;
      GimpRGB           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;
      GimpPDBStatusType d_status;
    };

### GimpParam

    typedef struct {
      GimpPDBArgType type;
      GimpParamData  data;
    } GimpParam;

### MAIN()

    #define     MAIN()

A macro that expands to the appropriate `main()` function for the platform being compiled for.

To use this macro, simply place a line that contains just the code `MAIN()` at the toplevel of your file. No semicolon should be used.

### gimp_main ()

    gint        gimp_main                       (const GimpPlugInInfo *info,
                                                 gint argc,
                                                 gchar *argv[]);

The main procedure that must be called with the PLUG_IN_INFO structure and the 'argc' and 'argv' that are passed to "main".

`info` : | the PLUG_IN_INFO structure
`argc` : | the number of arguments
`argv` : | the arguments
Returns : |

### gimp_quit ()

    void        gimp_quit                       (void);

Forcefully causes the gimp library to exit and close down its connection to main gimp application. This function never returns.

### gimp_install_procedure ()

    void        gimp_install_procedure          (const gchar *name,
                                                 const gchar *blurb,
                                                 const gchar *help,
                                                 const gchar *author,
                                                 const gchar *copyright,
                                                 const gchar *date,
                                                 const gchar *menu_label,
                                                 const gchar *image_types,
                                                 GimpPDBProcType type,
                                                 gint n_params,
                                                 gint n_return_vals,
                                                 const GimpParamDef *params,
                                                 const GimpParamDef *return_vals);

Installs a new procedure with the PDB (procedural database).

Call this function from within your Plug-In's `query()` function for each procedure your Plug-In implements.

The `name` parameter is mandatory and should be unique, or it will overwrite an already existing procedure (overwrite procedures only if you know what you're doing).

The `blurb`, `help`, `author`, `copyright` and `date` parameters are optional but then you shouldn't write procedures without proper documentation, should you.

`menu_label` defines the label that should be used for the procedure's menu entry (use NULL if the procedure shouldn't have a menu entry). The position where to register in the menu hierarchy is choosen using `gimp_plugin_menu_register()`. This function also still accepts the old (pre-2.2) way of registering a menu entry and takes a string in the form "<Domain>/Path/To/My/Menu" (e.g. "<Image>/Filters/Render/Useless").

`type` must be one of GIMP_PLUGIN or GIMP_EXTENSION. Note that temporary procedures must be installed using `gimp_install_temp_proc()`.

NOTE: Unlike the GIMP 1.2 API, GIMP_EXTENSION no longer means that the procedure's menu prefix is <Toolbox>, but that it will install temporary procedures. Therefore, the GIMP core will wait until the GIMP_EXTENSION procedure has called `gimp_extension_ack()`, which means that the procedure has done its initialization, installed its temporary procedures and is ready to run.

Not calling `gimp_extension_ack()` from a GIMP_EXTENSION procedure will cause th GIMP core to lock up.

Additionally, a GIMP_EXTENSION procedure with no parameters (`n_params` == 0 and `params` == NULL) is an "automatic" extension that will be automatically started on each GIMP startup.

`name` : | the procedure's name.
`blurb` : | a short text describing what the procedure does.
`help` : | the help text for the procedure (usually considerably longer than `blurb`).
`author` : | the procedure's author(s).
`copyright` : | the procedure's copyright.
`date` : | the date the procedure was added.
`menu_label` : | the label to use for the procedure's menu entry, or NULL if the procedure has no menu entry.
`image_types` : | the drawable types the procedure can handle.
`type` : | the type of the procedure.
`n_params` : | the number of parameters the procedure takes.
`n_return_vals` : | the number of return values the procedure returns.
`params` : | the procedure's parameters.
`return_vals` : | the procedure's return values.

### gimp_install_temp_proc ()

    void        gimp_install_temp_proc          (const gchar *name,
                                                 const gchar *blurb,
                                                 const gchar *help,
                                                 const gchar *author,
                                                 const gchar *copyright,
                                                 const gchar *date,
                                                 const gchar *menu_label,
                                                 const gchar *image_types,
                                                 GimpPDBProcType type,
                                                 gint n_params,
                                                 gint n_return_vals,
                                                 const GimpParamDef *params,
                                                 const GimpParamDef *return_vals,
                                                 GimpRunProc run_proc);

Installs a new temporary procedure with the PDB (procedural database).

A temporary procedure is a procedure which is only available while one of your Plug-In's "real" procedures is running.

See `gimp_install_procedure()` for most details.

`type` must be GIMP_TEMPORARY or the function will fail.

`run_proc` is the function which will be called to execute the procedure.

NOTE: Normally, Plug-In communication is triggered by the Plug-In and the GIMP core only responds to the Plug-In's requests. You must explicitely enable receiving of temporary procedure run requests using either `gimp_extension_enable()` or `gimp_extension_process()`. See this functions' documentation for details.

`name` : | the procedure's name.
`blurb` : | a short text describing what the procedure does.
`help` : | the help text for the procedure (usually considerably longer than `blurb`).
`author` : | the procedure's author(s).
`copyright` : | the procedure's copyright.
`date` : | the date the procedure was added.
`menu_label` : | the procedure's menu label, or NULL if the procedure has no menu entry.
`image_types` : | the drawable types the procedure can handle.
`type` : | the type of the procedure.
`n_params` : | the number of parameters the procedure takes.
`n_return_vals` : | the number of return values the procedure returns.
`params` : | the procedure's parameters.
`return_vals` : | the procedure's return values.
`run_proc` : | the function to call for executing the procedure.

### gimp_uninstall_temp_proc ()

    void        gimp_uninstall_temp_proc        (const gchar *name);

Uninstalls a temporary procedure which has previously been installed using `gimp_install_temp_proc()`.

`name` : | the procedure's name

### gimp_run_procedure ()

    GimpParam*  gimp_run_procedure              (const gchar *name,
                                                 gint *n_return_vals,
                                                 ...);

This function calls a GIMP procedure and returns its return values.

The procedure's parameters are given by a va_list in the format (type, value, type, value) and must be terminated by GIMP_PDB_END.

This function converts the va_list of parameters into an array and passes them to `gimp_run_procedure2()`.

`name` : | the name of the procedure to run
`n_return_vals` : | return location for the number of return values
`...` : | list of procedure parameters
Returns : | the procedure's return values.

### gimp_run_procedure2 ()

    GimpParam*  gimp_run_procedure2             (const gchar *name,
                                                 gint *n_return_vals,
                                                 gint n_params,
                                                 const GimpParam *params);

This function calls a GIMP procedure and returns its return values.

`name` : | the name of the procedure to run
`n_return_vals` : | return location for the number of return values
`n_params` : | the number of parameters the procedure takes.
`params` : | the procedure's parameters array.
Returns : | the procedure's return values.

### gimp_destroy_params ()

    void        gimp_destroy_params             (GimpParam *params,
                                                 gint n_params);

Destroys a GimpParam array as returned by `gimp_run_procedure()`

`params` : | the GimpParam array to destroy
`n_params` : | the number of elements in the array

### gimp_destroy_paramdefs ()

    void        gimp_destroy_paramdefs          (GimpParamDef *paramdefs,
                                                 gint n_params);

Destroys a GimpParamDef array as returned by `gimp_query_procedure()`

`paramdefs` : | the GimpParamDef array to destroy
`n_params` : | the number of elements in the array

### gimp_tile_width ()

    guint       gimp_tile_width                 (void);

Returns the tile_width the GIMP is using. This is a constant value given at Plug-In config time.

Returns : | the tile_width

### gimp_tile_height ()

    guint       gimp_tile_height                (void);

Returns the tile_height the GIMP is using. This is a constant value given at Plug-In config time.

Returns : | the tile_height

### gimp_shm_ID ()

    gint        gimp_shm_ID                     (void);

Returns the shared memory ID used for passing tile data between the GIMP core and the Plug-In. This is a constant value given at Plug-In config time.

Returns : | the shared memory ID

### gimp_shm_addr ()

    guchar*     gimp_shm_addr                   (void);

Returns the address of the shared memory segment used for passing tile data between the GIMP core and the Plug-In. This is a constant value given at Plug-In config time.

Returns : | the shared memory address

### gimp_gamma ()

    gdouble     gimp_gamma                      (void);

Returns the global gamma value the GIMP and all its Plug-Ins should use. This is a constant value given at Plug-In config time.

NOTE: this feature is unimplemented.

Returns : | the gamma value

### gimp_install_cmap ()

    gboolean    gimp_install_cmap               (void);

Returns whether or not the Plug-In should allocate an own colormap when running on an 8 bit display. This is a constant value given at Plug-In config time.

See also: `gimp_min_colors()`

Returns : | the install_cmap boolean

### gimp_min_colors ()

    gint        gimp_min_colors                 (void);

Returns the minimum number of colors to use when allocating an own colormap on 8 bit displays. This is a constant value given at Plug-In config time.

See also: `gimp_install_cmap()`

Returns : | the minimum number of colors to allocate

### gimp_show_tool_tips ()

    gboolean    gimp_show_tool_tips             (void);

Returns whether or not the Plug-In should show tooltips. This is a constant value given at Plug-In config time.

Returns : | the show_tool_tips boolean

### gimp_show_help_button ()

    gboolean    gimp_show_help_button           (void);

Returns whether or not GimpDialog should automatically add a help button if help_func and help_id are given.

Returns : | the show_help_button boolean

Since GIMP 2.2

### gimp_check_size ()

    GimpCheckSize gimp_check_size               (void);

Returns the size of the checkerboard to be used in previews. This is a constant value given at Plug-In config time.

Returns : | the check_size value

Since GIMP 2.2

### gimp_check_type ()

    GimpCheckType gimp_check_type               (void);

Returns the type of the checkerboard to be used in previews. This is a constant value given at Plug-In config time.

Returns : | the check_type value

Since GIMP 2.2

### gimp_default_display ()

    gint32      gimp_default_display            (void);

Returns the default display ID. This corresponds to the display the running procedure's menu entry was invoked from. This is a constant value given at Plug-In config time.

Returns : | the default display ID

### gimp_wm_class ()

    const gchar* gimp_wm_class                  (void);

Returns the window manager class to be used for plug-in windows. This is a constant value given at Plug-In config time.

Returns : | the window manager class

### gimp_display_name ()

    const gchar* gimp_display_name              (void);

Returns the display to be used for plug-in windows. This is a constant value given at Plug-In config time.

Returns : | the display name

### gimp_monitor_number ()

    gint        gimp_monitor_number             (void);

Returns the monitor number to be used for plug-in windows. This is a constant value given at Plug-In config time.

Returns : | the monitor number

### gimp_get_progname ()

    const gchar* gimp_get_progname              (void);

Returns the Plug-In's executable name.

Returns : | the executable name

### gimp_extension_enable ()

    void        gimp_extension_enable           (void);

Enables asnychronous processing of messages from the main GIMP application.

Normally, a plug-in is not called by the GIMP except for the call to the procedure it implements. All subsequent communication is triggered by the plug-in and all messages sent from the GIMP to the plug-in are just answers to requests the plug-in made.

If the plug-in however registered temporary procedures using `gimp_install_temp_proc()`, it needs to be able to receive requests to execute them. Usually this will be done by running `gimp_extension_process()` in an endless loop.

If the plug-in cannot use `gimp_extension_process()`, i.e. if it has a GUI and is hanging around in a GMainLoop, it must call `gimp_extension_enable()`.

Note that the plug-in does not need to be a GIMP_EXTENSION to register temporary procedures.

See also: `gimp_install_procedure()`, `gimp_install_temp_proc()`

### gimp_extension_ack ()

    void        gimp_extension_ack              (void);

Notify the main GIMP application that the extension has been properly initialized and is ready to run.

This function must be called from every procedure that was registered as GIMP_EXTENSION.

Subsequently, extensions can process temporary procedure run requests using either `gimp_extension_enable()` or `gimp_extension_process()`.

See also: `gimp_install_procedure()`, `gimp_install_temp_proc()`

### gimp_extension_process ()

    void        gimp_extension_process          (guint timeout);

Processes one message sent by the GIMP and returns.

Call this function in an endless loop after calling `gimp_extension_ack()` to process requests for running temporary procedures.

See `gimp_extension_enable()` for an asynchronous way of doing the same if running an endless loop is not an option.

See also: `gimp_install_procedure()`, `gimp_install_temp_proc()`

`timeout` : | The timeout (in ms) to use for the `select()` call.

### gimp_parasite_find ()

    GimpParasite* gimp_parasite_find            (const gchar *name);

Finds the named parasite.

Finds and returns the named parasite that was previously attached to the gimp.

`name` : | The name of the parasite to find.
Returns : | The found parasite.

### gimp_parasite_list ()

    gboolean    gimp_parasite_list              (gint *num_parasites,
                                                 gchar ***parasites);

List all parasites.

Returns a list of all currently attached parasites.

`num_parasites` : | The number of attached parasites.
`parasites` : | The names of currently attached parasites.
Returns : | TRUE on success.

### gimp_parasite_attach ()

    gboolean    gimp_parasite_attach            (GimpParasite *parasite);

Add a parasite to the gimp.

This procedure attaches a parasite to the gimp. It has no return values.

`parasite` : | The parasite to attach to the gimp.
Returns : | TRUE on success.

### gimp_parasite_detach ()

    gboolean    gimp_parasite_detach            (const gchar *name);

Removes a parasite from the gimp.

This procedure detaches a parasite from the gimp. It has no return values.

`name` : | The name of the parasite to detach from the gimp.
Returns : | TRUE on success.

### gimp_attach_new_parasite ()

    void        gimp_attach_new_parasite        (const gchar *name,
                                                 gint flags,
                                                 gint size,
                                                 gconstpointer data);

Convenience function that creates a parasite and attaches it to the GIMP.

See Also: `gimp_parasite_attach()`

`name` : | the name of the GimpParasite to create and attach.
`flags` : | the flags set on the GimpParasite.
`size` : | the size of the parasite data in bytes.
`data` : | a pointer to the data attached with the GimpParasite.