8. GIMP Library Reference

void gimp_add_callback (int DIALOG_ID, int ITEM_ID, GimpItemCallbackProc CALLBACK, void *CALLBACK_DATA)

This function adds CALLBACK as callback function of the item ITEM_ID. The callback function handles CALLBACK_DATA as data of the item.

void gimp_background_color (unsigned char *RED, unsigned char *GREEN, unsigned char *BLUE)

This function returns the current background color in the GIMP application.

int gimp_cancel_item_id (int DIALOG_ID)

This function returns the handle of the Cancel-Button of dialog DIALOG_ID. You need it to add a callback for the Button. See also: gimp_add_callback (), gimp_ok_item_id ()

void gimp_change_item (int DIALOG_ID, int ITEM_ID, long DATA_SIZE, void *DATA)

This function sets the value of DATA as new value of the item ITEM_ID. The size of the DATA-type has to be stored in DATA_SIZE.

void gimp_close_dialog (int DIALOG_ID, int RETURN_VAL)

This function closes the dialog with the handle DIALOG_ID. The value of RETURN_VAL will be returned by gimp_show_dialog (). See also: gimp_show_dialog ()

void gimp_delete_item (int DIALOG_ID, int ITEM_ID)

This function deletes the item ITEM_ID from the dialog DIALOG_ID.

void gimp_destroy_image (Image IMAGE)

This function tells the GIMP library to free its link to IMAGE and to tell the GIMP to also free its link. The result is that IMAGE will be destroyed.

void gimp_display_image (Image IMAGE)

This function displays an image. A new view is created in the process. Therefore, it is not necessary to display an image that is already displayed. (This function is used mainly by file plug-ins which must tell the GIMP to display a newly created image).

void gimp_foreground_color (unsigned char *RED, unsigned char *GREEN, unsigned char *BLUE)

This function returns the current foreground color in the GIMP application.

void gimp_free_image (Image IMAGE)

This function tells the GIMP library to free its link to IMAGE. The image is not actually destroyed since the GIMP will retain its link.

Image gimp_get_input_image (long ID)

This function gets an input image with the given ID. Every image in the main GIMP application has a unique ID value assigned to it at creation. Values are assigned starting from 1. This function can be used to get any valid image in the GIMP. However, this action is not recommended since it is impossible to tell which ID's are valid.

The main usage is to get the default image which is specified by an ID value of 0. (This is used since no actual image in the GIMP will have an ID of 0).

Input images are defined to be read-only. That is, the programmer should not modify the image. (This is enforced by the library by only read-only to the shared memory segment).

Image gimp_get_output_image (long ID)

gimp_get_output_image is analogous to gimp_get_input_image except that it gets an output image. An output image is defined to be read-write. Meaning that data can be read to and written from. It may seem strange, but getting both the input image and output image for the same ID actually returns two different images and two different data segments. Writing to the input image does not affect the output image and vice-versa.

void *gimp_get_params (void)

This functions returns a pointer to a previously saved data structure.

See also: gimp_set_params

gimp.h

This is the standard header for GIMP plug-ins. It has to be included with

#include "gimp.h"

.

void gimp_hide_item (int DIALOG_ID, int ITEM_ID)

This function makes the item ITEM_ID of the dialog DIALOG_ID invisible.

void gimp_image_area (Image IMAGE, int *X1, int *Y1, int *X2, int *Y2)

This function returns the active area of operation for a plug-in. The area is returned as a rectangle defined by the upper-left corner (X1, Y1) and the lower-right corner (X2, Y2). This is useful for effects filters which have their results masked by the current selection in an image. By only operating within the active area a slow running plug-in can dramatically increase its speed. (Even a fast running plug-in can dramatically increase its speed since the user may have only selected a small portion of the image).

It should be noted that a plug-in should run the same whether or not it uses the information about the active image area. That is, operating on the entire image and operating on the active area should have the same end effect from the users point of view.

long gimp_image_channels (Image IMAGE)

This function returns an images channels. RGB images have 3 channels. Grayscale and indexed color images have 1 channel.

void* gimp_image_cmap (Image IMAGE)

This function returns the colormap associated with an image. It is only valid for indexed color images. The colormap is a series of RGB triplets where each triplet is 3 bytes. The size of the colormap is always 768 bytes, however, only the first gimp_image_colors (IMAGE) triplets are valid.

long gimp_image_colors (Image IMAGE)

This function returns the number of colors in an indexed color image. It is only valid for indexed color images.

void* gimp_image_data (Image IMAGE)

This function returns the actual pixel data for the image. For RGB images the data is laid out as a series of RGB triplets where each triplet is 3 bytes. For grayscale and indexed color images, each pixel value is a single byte corresponding to a grayscale value or pixel index respectively.

long gimp_image_height (Image IMAGE)

This function returns an images height.

char* gimp_image_name (Image IMAGE)

This function returns an images name.

ImageType gimp_image_type (Image IMAGE)

This function returns the type of an image. The type is one of RGB_IMAGE, GRAY_IMAGE, INDEXED_IMAGE, or UNKNOWN_IMAGE. If UNKNOWN_IMAGE is returned an error has occurred within the library. (ie. This should never happen).

long gimp_image_width (Image IMAGE)

This function returns an images width.

int gimp_init (int ARGC, char **ARGV)

This function intializes the GIMP library. The arguments ARGC and ARGV are simply the ARGC and ARGV values passed into main() upon invocation. Returns >0 (true) if initialization was ok. See also: gimp_quit ()

void gimp_install_load_save_handlers (GimpLoadSaveProc load, save)

This function installs two handlers for file plug-ins. load and save refer to the file load and save functions.

int gimp_new_check_button (int DIALOG_ID, int PARENT_ID, char *TITLE)

This function creates a new check button. It returns a handle of the new check button.

int gimp_new_column_group (int DIALOG_ID, int PARENT_ID, int GROUP_TYPE, char *TITLE)

This function creates a new group box. Members of the new box are shown in a column. It returns a handle of the new group box.

int gimp_new_dialog (char *TITLE)

This function creates a new dialog for user interactions. It returns a handle of the new dialog window.

int gimp_new_frame (int DIALOG_ID, int PARENT_ID, char *TITLE)

This function creates a new frame. It returns a handle of the new frame.

Image gimp_new_image (char *TITLE, long WIDTH, long HEIGHT, ImageType TYPE)

This function creates a new image with the given title, width, height and type. The new image is returned in the opaque type Image. Use the gimp_image_* functions to get information out of the image.

TYPE should be specified as one of RGB_IMAGE, GRAY_IMAGE or INDEXED_IMAGE to create a new RGB image, grayscale image or indexed color image respectively.

int gimp_new_image_menu (int DIALOG_ID, int PARENT_ID, char CONSTRAINT, char *TITLE)

This function creates an image choose box which contains all opened images. CONSTRAINT is composed by combining the constants IMAGE_CONSTRAIN_RGB, IMAGE_CONSTRAIN_GRAY, IMAGE_CONSTRAIN_INDEXED and IMAGE_CONSTRAIN_ALL with OR operators.

int gimp_new_label (int DIALOG_ID, int PARENT_ID, char *TITLE)

This function creates a new label. It returns a handle of the new label.

int gimp_new_push_button (int DIALOG_ID, int PARENT_ID, char *TITLE)

This function creates a new push button. It returns a handle of the new push button.

int gimp_new_radio_button (int DIALOG_ID, int PARENT_ID, char *TITLE)

This function creates a new radio button. It returns a handle of the new radio button.

int gimp_new_row_group (int DIALOG_ID, int PARENT_ID, int GROUP_TYPE, char *TITLE)

This function creates a new group box. Members of the new box are shown in a row. It returns a handle of the new group box.

int gimp_new_scale (int DIALOG_ID, int PARENT_ID, long MIN, long MAX, long START_VALUE, long PRECISION)

This function creates a new scale. It returns a handle of the new scale.

int gimp_new_text (int DIALOG_ID, int PARENT_ID, char *TITLE)

This function creates a new text entry field. It returns a handle of the new text entry field.

int gimp_ok_item_id (int DIALOG_ID)

This function returns the handle of the OK-Button of dialog DIALOG_ID. You need it to add a callback for the Button. See also: gimp_add_callback (), gimp_cancel_item_id ()

void gimp_quit (void)

This function closes all shared memory blocks and disconnects from The GIMP. See also: gimp_init ()

void gimp_set_image_colors (Image IMAGE, void *CMAP, long NCOLORS)

This function sets an images colormap and the number of colors associated with it. It is only valid for indexed color images.

void gimp_set_params (long size, void *data)

This function stores a size bytes data structure that can be recovered with gimp_get_params () See also: gimp_get_params ()

int gimp_show_dialog (int DIALOG_ID)

This function starts the dialog with the handle DIALOG_ID and normally returns after the user pressed the Ok- or Cancel-Button. It should return true (>0) if the dialog has ended with the Ok-Button. It should return false (0) if the dialog has ended with the Cancel-Button. See also: gimp_close_dialog ()

void gimp_show_item (int DIALOG_ID, int ITEM_ID)

This function shows the item ITEM_ID in the dialog DIALOG_ID.

void gimp_update_dialog (int)

This function redraws a dialog.

void gimp_update_image (Image IMAGE)

This function tells the GIMP to redraw an image. The image is redrawn in every view.

---

                        gimp_update_image (input);
                        

---