gimp: GIMP Library Reference Manual

## gimp gimp — Miscellaneous procedures |

## Functions

gchar * | gimp_version ()
gint | gimp_getpid ()
void | (*GimpInitProc) ()
void | (*GimpQuitProc) ()
void | (*GimpQueryProc) ()
void | (*GimpRunProc) ()
#define | MAIN
gint | gimp_main ()
void | gimp_quit ()
void | gimp_install_procedure ()
void | gimp_install_temp_proc ()
void | gimp_uninstall_temp_proc ()
GimpParam * | gimp_run_procedure ()
GimpParam * | gimp_run_procedure2 ()
void | gimp_destroy_params ()
void | gimp_destroy_paramdefs ()
const gchar * | gimp_get_pdb_error ()
GimpPDBStatusType | gimp_get_pdb_status ()
guint | gimp_tile_width ()
guint | gimp_tile_height ()
gint | gimp_shm_ID ()
guchar * | gimp_shm_addr ()
gdouble | gimp_gamma ()
gboolean | gimp_install_cmap ()
gint | gimp_min_colors ()
gboolean | gimp_show_tool_tips ()
gboolean | gimp_show_help_button ()
gboolean | gimp_export_color_profile ()
gboolean | gimp_export_exif ()
gboolean | gimp_export_iptc ()
gboolean | gimp_export_xmp ()
GimpCheckSize | gimp_check_size ()
GimpCheckType | gimp_check_type ()
gint32 | gimp_default_display ()
const gchar * | gimp_wm_class ()
const gchar * | gimp_display_name ()
gint | gimp_monitor_number ()
guint32 | gimp_user_time ()
const gchar * | gimp_icon_theme_dir ()
const gchar * | gimp_get_progname ()
void | gimp_extension_enable ()
void | gimp_extension_ack ()
void | gimp_extension_process ()
gboolean | gimp_attach_parasite ()
gboolean | gimp_detach_parasite ()
GimpParasite * | gimp_parasite_find ()
gboolean | gimp_parasite_list ()
GimpParasite * | gimp_get_parasite ()
gchar ** | gimp_get_parasite_list ()
gboolean | gimp_parasite_attach ()
gboolean | gimp_parasite_detach ()
gboolean | gimp_attach_new_parasite ()

## Types and Values

#define | gimp_get_data
#define | gimp_get_data_size
#define | gimp_set_data
| GimpPlugInInfo
| GimpParamDef
| GimpParamRegion
| GimpParamData
| GimpParam

## Description

Miscellaneous procedures not fitting in any category.

## Functions

### gimp_version ()

    gchar *
    gimp_version (void);

Returns the host GIMP version.

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

#### Returns

GIMP version number.

### 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: 2.4

### 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);

### 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".

#### Parameters

info | the PLUG_IN_INFO structure |
argc | the number of arguments |
argv | the arguments |

#### Returns

an exit status as defined by the C library, on success EXIT_SUCCESS.

### 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. The position where to register in the menu hierarchy is chosen 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").

Note that registering a full (pre-2.2-style) menu path is deprecated and will cause a failure in GIMP 3.0 and newer.

It is possible to register a procedure only for keyboard-shortcut activation by passing a `menu_label` to `gimp_install_procedure()` but not registering any menu path with `gimp_plugin_menu_register()`. In this case, the given `menu_label` will only be used as the procedure's user-visible name in the keyboard shortcut editor.

`image_types` is a comma separated list of image types, or actually drawable types, that this procedure can deal with. Wildcards are possible here, so you could say "RGB*" instead of "RGB, RGBA" or "*" for all image types. If the procedure doesn't need an image to run, use the empty string.

`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 the 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.

#### Parameters

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 explicitly enable receiving of temporary procedure run requests using either `gimp_extension_enable()` or `gimp_extension_process()`. See this functions' documentation for details.

#### Parameters

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

#### Parameters

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.

#### Parameters

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 unless there was an error, in which case the zero-th return value will be the error status, and the first return value will be a string detailing the error.

### 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 GIMP's toolbox.

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

#### Parameters

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 unless there was an error, in which case the zero-th return value will be the error status, and if there are two values returned, the other return value will be a string detailing the error.

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

#### Parameters

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

#### Parameters

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

### gimp_get_pdb_error ()

    const gchar *
    gimp_get_pdb_error (void);

Retrieves the error message from the last procedure call.

If a procedure call fails, then it might pass an error message with the return values. Plug-ins that are using the libgimp C wrappers don't access the procedure return values directly. Thus libgimp stores the error message and makes it available with this function. The next procedure call unsets the error message again.

The returned string is owned by libgimp and must not be freed or modified.

#### Returns

the error message

Since: 2.6

### gimp_get_pdb_status ()

    GimpPDBStatusType
    gimp_get_pdb_status (void);

Retrieves the status from the last procedure call.

#### Returns

the GimpPDBStatusType.

Since: 2.10

### gimp_tile_width ()

    guint
    gimp_tile_width (void);

Returns the tile width GIMP is using.

This is a constant value given at plug-in configuration time.

#### Returns

the tile_width

### gimp_tile_height ()

    guint
    gimp_tile_height (void);

Returns the tile height GIMP is using.

This is a constant value given at plug-in configuration 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 configuration 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 configuration time.

#### Returns

the shared memory address

### gimp_gamma ()

    gdouble
    gimp_gamma (void);

`gimp_gamma` is deprecated and should not be used in newly-written code.

Returns the global gamma value GIMP and all its plug-ins should use.

This is a constant value.

NOTE: This function will always return 2.2, the gamma value for sRGB. If you need the actual gamma value of a drawable, look at its format.

See also: `gimp_drawable_get_format()`.

`Deprecated` : 2.8.4

#### Returns

the gamma value

### gimp_install_cmap ()

    gboolean
    gimp_install_cmap (void);

`gimp_install_cmap` is deprecated and should not be used in newly-written code.

Returns whether or not the plug-in should allocate an own colormap when running on an 8 bit display. See also: `gimp_min_colors()`.

This is a constant value given at plug-in configuration time.

`Deprecated` : 2.8

#### Returns

the install_cmap boolean

### gimp_min_colors ()

    gint
    gimp_min_colors (void);

`gimp_min_colors` is deprecated and should not be used in newly-written code.

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 configuration time.

See also: `gimp_install_cmap()`

`Deprecated` : 2.8

#### 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 tool-tips.

This is a constant value given at plug-in configuration 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.

This is a constant value given at plug-in configuration time.

#### Returns

the show_help_button boolean

Since: 2.2

### gimp_export_color_profile ()

    gboolean
    gimp_export_color_profile (void);

Returns whether file plug-ins should default to exporting the image's color profile.

#### Returns

TRUE if preferences are set to export the color profile.

Since: 2.10.4

### gimp_export_exif ()

    gboolean
    gimp_export_exif (void);

Returns whether file plug-ins should default to exporting Exif metadata, according preferences (original settings is FALSE since metadata can contain sensitive information).

#### Returns

TRUE if preferences are set to export Exif.

Since: 2.10

### gimp_export_iptc ()

    gboolean
    gimp_export_iptc (void);

Returns whether file plug-ins should default to exporting IPTC metadata, according preferences (original settings is FALSE since metadata can contain sensitive information).

#### Returns

TRUE if preferences are set to export IPTC.

Since: 2.10

### gimp_export_xmp ()

    gboolean
    gimp_export_xmp (void);

Returns whether file plug-ins should default to exporting XMP metadata, according preferences (original settings is FALSE since metadata can contain sensitive information).

#### Returns

TRUE if preferences are set to export XMP.

Since: 2.10

### 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 configuration time.

#### Returns

the check_size value

Since: 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 configuration time.

#### Returns

the check_type value

Since: 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 configuration 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 configuration 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 configuration time. Will return NULL if GIMP has been started with no GUI, either via "--no-interface" flag, or a console build.

#### 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 configuration time.

#### Returns

the monitor number

### gimp_user_time ()

    guint32
    gimp_user_time (void);

Returns the timestamp of the user interaction that should be set on the plug-in window. This is handled transparently, plug-in authors do not have to care about it.

This is a constant value given at plug-in configuration time.

#### Returns

timestamp for plug-in window

Since: 2.6

### gimp_icon_theme_dir ()

    const gchar *
    gimp_icon_theme_dir (void);

### 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 asynchronous processing of messages from the main GIMP application.

Normally, a plug-in is not called by GIMP except for the call to the procedure it implements. All subsequent communication is triggered by the plug-in and all messages sent from 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 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()`

#### Parameters

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

### gimp_attach_parasite ()

    gboolean
    gimp_attach_parasite (const GimpParasite *parasite);

Add a global parasite.

This procedure attaches a global parasite. It has no return values.

#### Parameters

parasite | The parasite to attach. |

#### Returns

TRUE on success.

Since: 2.8

### gimp_detach_parasite ()

    gboolean
    gimp_detach_parasite (const gchar *name);

Removes a global parasite.

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

#### Parameters

name | The name of the parasite to detach. |

#### Returns

TRUE on success.

Since: 2.8

### gimp_parasite_find ()

    GimpParasite *
    gimp_parasite_find (const gchar *name);

`gimp_parasite_find` is deprecated and should not be used in newly-written code.

Use `gimp_get_parasite()` instead.

#### Parameters

name | The name of the parasite to find. |

#### Returns

The found parasite.

### gimp_parasite_list ()

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

`gimp_parasite_list` is deprecated and should not be used in newly-written code.

Use `gimp_get_parasite_list()` instead.

#### Parameters

num_parasites | The number of attached parasites. |
parasites | The names of currently attached parasites. |

#### Returns

TRUE on success.

### gimp_get_parasite ()

    GimpParasite *
    gimp_get_parasite (const gchar *name);

Look up a global parasite.

Finds and returns the global parasite that was previously attached.

#### Parameters

name | The name of the parasite to find. |

#### Returns

The found parasite.

Since: 2.8

### gimp_get_parasite_list ()

    gchar **
    gimp_get_parasite_list (gint *num_parasites);

List all parasites.

Returns a list of all currently attached global parasites.

#### Parameters

num_parasites | The number of attached parasites. |

#### Returns

The names of currently attached parasites. The returned value must be freed with `g_strfreev()`.

Since: 2.8

### gimp_parasite_attach ()

    gboolean
    gimp_parasite_attach (const GimpParasite *parasite);

`gimp_parasite_attach` is deprecated and should not be used in newly-written code.

Use `gimp_attach_parasite()` instead.

#### Parameters

parasite | The parasite to attach. |

#### Returns

TRUE on success.

### gimp_parasite_detach ()

    gboolean
    gimp_parasite_detach (const gchar *name);

`gimp_parasite_detach` is deprecated and should not be used in newly-written code.

Use `gimp_detach_parasite()` instead.

#### Parameters

name | The name of the parasite to detach. |

#### Returns

TRUE on success.

### gimp_attach_new_parasite ()

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

`gimp_attach_new_parasite` is deprecated and should not be used in newly-written code.

Use `gimp_attach_parasite()` instead.

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

#### Parameters

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

## Types and Values

### 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

### gimp_set_data

    #define gimp_set_data         gimp_procedural_db_set_data

### GimpPlugInInfo

    typedef struct {
      GimpInitProc  init_proc;
      GimpQuitProc  quit_proc;
      GimpQueryProc query_proc;
      GimpRunProc   run_proc;
    } GimpPlugInInfo;

#### Members

GimpInitProc `init_proc`; | called when the gimp application initially starts up |
GimpQuitProc `quit_proc`; | called when the gimp application exits |
GimpQueryProc `query_proc`; | called by gimp so that the plug-in can inform the gimp of what it does. (ie. installing a procedure database procedure). |
GimpRunProc `run_proc`; | called to run a procedure the plug-in installed in the procedure database. |

### GimpParamDef

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

### GimpParamRegion

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

### GimpParamData

### GimpParam

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