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.

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.

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.

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

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.

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.

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;
+