## 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);
    gint        gimp_getpid                     (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            (const GimpParasite *parasite);
    gboolean    gimp_parasite_detach            (const gchar *name);
    gboolean    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_getpid ()

    gint        gimp_getpid                     (void);

Returns the PID of the host gimp process.

This procedure returns the process ID of the currently running gimp.

Returns : | The PID.

Since GIMP 2.4

### 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; /* deprecated */
      gint32            d_vectors;
      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()`. Please look there for further information.

`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. To get more information about the available procedures and the parameters they expect, please have a look at the Procedure Browser as found in the Xtns menu in the GIMP's Toolbox.

As soon as you don't need the return values any longer, you should free them using `gimp_destroy_params()`.

`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()` or `gimp_run_procedure2()`.

`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            (const 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 ()

    gboolean    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.

`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.
Returns : | TRUE on successful creation and attachment of the new parasite. See Also: `gimp_parasite_attach()`