![]() |
![]() |
![]() |
GIMP Library Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
gimpgimp — Main functions needed for building a GIMP plug-in. This header includes all other GIMP Library headers. |
gchar* gimp_version (void
); gint gimp_getpid (void
); #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
); const gchar * gimp_get_pdb_error (void
); 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
); guint32 gimp_user_time (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
);
Main functions needed for building a GIMP plug-in. This header includes all other GIMP Library headers.
gchar* gimp_version (void
);
Returns the host GIMP version.
This procedure returns the version number of the currently running GIMP.
Returns : |
GIMP version number. |
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
void (*GimpRunProc) (const gchar *name
,gint n_params
,const GimpParam *param
,gint *n_return_vals
,GimpParam **return_vals
);
|
|
|
|
|
|
|
|
|
typedef struct { /* called when the gimp application initially starts up */ GimpInitProc init_proc; /* called when the gimp application exits */ GimpQuitProc quit_proc; /* called by 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;
typedef struct { gint32 x; gint32 y; gint32 width; gint32 height; } GimpParamRegion;
union _GimpParamData { gint32 d_int32; gint16 d_int16; guint8 d_int8; gdouble d_float; gchar *d_string; gint32 *d_int32array; gint16 *d_int16array; guint8 *d_int8array; gdouble *d_floatarray; gchar **d_stringarray; GimpRGB *d_colorarray; 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; };
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".
|
the PLUG_IN_INFO structure |
|
the number of arguments |
|
the arguments |
Returns : |
void gimp_quit (void
);
Forcefully causes the GIMP library to exit and close down its connection to main gimp application. This function never returns.
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").
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.
|
the procedure's name. |
|
a short text describing what the procedure does. |
|
the help text for the procedure (usually considerably
longer than blurb ).
|
|
the procedure's author(s). |
|
the procedure's copyright. |
|
the date the procedure was added. |
|
the label to use for the procedure's menu entry, or NULL if the procedure has no menu entry. |
|
the drawable types the procedure can handle. |
|
the type of the procedure. |
|
the number of parameters the procedure takes. |
|
the number of return values the procedure returns. |
|
the procedure's parameters. |
|
the procedure's return values. |
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.
|
the procedure's name. |
|
a short text describing what the procedure does. |
|
the help text for the procedure (usually considerably
longer than blurb ).
|
|
the procedure's author(s). |
|
the procedure's copyright. |
|
the date the procedure was added. |
|
the procedure's menu label, or NULL if the procedure has no menu entry. |
|
the drawable types the procedure can handle. |
|
the type of the procedure. |
|
the number of parameters the procedure takes. |
|
the number of return values the procedure returns. |
|
the procedure's parameters. |
|
the procedure's return values. |
|
the function to call for executing the procedure. |
void gimp_uninstall_temp_proc (const gchar *name
);
Uninstalls a temporary procedure which has previously been
installed using gimp_install_temp_proc()
.
|
the procedure's name |
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.
|
the name of the procedure to run |
|
return location for the number of return values |
|
list of procedure parameters |
Returns : |
the procedure's return values. |
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()
.
|
the name of the procedure to run |
|
return location for the number of return values |
|
the number of parameters the procedure takes. |
|
the procedure's parameters array. |
Returns : |
the procedure's return values. |
void gimp_destroy_params (GimpParam *params
,gint n_params
);
Destroys a GimpParam array as returned by gimp_run_procedure()
or
gimp_run_procedure2()
.
|
the GimpParam array to destroy |
|
the number of elements in the array |
void gimp_destroy_paramdefs (GimpParamDef *paramdefs
,gint n_params
);
Destroys a GimpParamDef array as returned by
gimp_procedural_db_proc_info()
.
|
the GimpParamDef array to destroy |
|
the number of elements in the array |
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 ligimp 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 GIMP 2.6
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 |
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 |
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 |
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 |
gdouble gimp_gamma (void
);
Returns the global gamma value GIMP and all its plug-ins should use.
This is a constant value given at plug-in configuration time.
NOTE: This function will always return 2.2, the gamma value for sRGB. There's currently no way to change this and all operations should assume that pixel data is in the sRGB colorspace.
Returns : |
the gamma value |
gboolean gimp_install_cmap (void
);
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.
Returns : |
the install_cmap boolean |
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 configuration time.
See also: gimp_install_cmap()
Returns : |
the minimum number of colors to allocate |
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 |
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 GIMP 2.2
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 GIMP 2.2
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 GIMP 2.2
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 |
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 |
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.
Returns : |
the display name |
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 |
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 GIMP 2.6
const gchar * gimp_get_progname (void
);
Returns the plug-in's executable name.
Returns : |
the executable name |
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()
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()
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()
|
The timeout (in ms) to use for the select() call.
|
GimpParasite* gimp_parasite_find (const gchar *name
);
Look up a global parasite.
Finds and returns the global parasite that was previously attached.
|
The name of the parasite to find. |
Returns : |
The found parasite. |
gboolean gimp_parasite_list (gint *num_parasites
,gchar ***parasites
);
List all parasites.
Returns a list of all currently attached global parasites.
|
The number of attached parasites. |
|
The names of currently attached parasites. |
Returns : |
TRUE on success. |
gboolean gimp_parasite_attach (const GimpParasite *parasite
);
Add a global parasite.
This procedure attaches a global parasite. It has no return values.
|
The parasite to attach. |
Returns : |
TRUE on success. |
gboolean gimp_parasite_detach (const gchar *name
);
Removes a global parasite.
This procedure detaches a global parasite from. It has no return values.
|
The name of the parasite to detach. |
Returns : |
TRUE on success. |
gboolean gimp_attach_new_parasite (const gchar *name
,gint flags
,gint size
,gconstpointer data
);
Convenience function that creates a parasite and attaches it to GIMP.
|
the name of the GimpParasite to create and attach. |
|
the flags set on the GimpParasite. |
|
the size of the parasite data in bytes. |
|
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()
|