You are here

C-code or script to retrieve user selected region

I am a beginner. I started to learn GIMP plugin development with C since few days.
I need a C-code or script to help me retrieve the user selected region.
I am planning to write a plugin to edit the user selected region only and leave the other area un-touched.
Can any one guide me where I can search for an answer ? Or any plugin source that has this feature so i can learn from it ?


Open Gimp go to Help>Procedure Browser - type in selection
Here is one of many in the list. :)



The basics to get you started can be found in the GIMP plug-in documentation, however, that documentation is a bit terse on how selections are handled (though the information is there).

There are three ways that your plug-in can modify the contents of an image's drawable:

  • By calling PDB functions (filters and plug-ins) that modify the drawable.
  • By modifying the drawable's data directly.
  • By making a "working copy" of the drawable, modifying that copy, and then merging it back with the original drawable.

For the first method, the selection is automatically handled by whatever filter, plug-in, or script you are using. For example, if your plug-in uses the Gaussian Blur filter on a layer, only the selected region of the original layer will get blurred. Your plug-in doesn't need to worry about the details of how the Gaussian Blur filter handles this, your plug-in only needs to make sure the appropriate region is selected.

The second method is highly discouraged -- your plug-in should never directly modify the original drawable. Modifying the drawable directly will interfere with the UNDO history, GIMP multi-threading capabilities, and GIMP's general knowledge about the state of the image.

You should use the third method if you want your plug-in to modify the pixels of a drawable and you can not (or you do not want to) use the high-level filters and plug-ins already available. The documentation in the above link covers the details of this process, but here is a broad overview:

  • Create a pixel region of the appropriate size
  • Copy the data from the original drawable to your pixel region
  • Modify the pixel region.
  • Merge the modified pixel region back into the original drawable.

Selections play two roles in this process. First, selections are typically used to determine the appropriate size of your pixel region. There is (usually) little sense in processing an entire drawable if only a small portion of it is selected, so generally your plug-in will fetch the bounds of the selection (the width, height, and offsets) and only process that region.

Bear in mind that the pixel region will be rectangular and that your plug-in will be processing the entire rectangular region. Even if the selection is elliptical or some peculiar shape, the "working copy" will contain all of the original rectangular area within the selection boundaries (similar to how when you float a selection to a new layer using menu commands, the resulting layer is rectangular). The actual "workhorse" code of your plug-in, which applies some algorithm to the pixel region, will ignore the selection while it is processing this rectangular pixel region.

The second role that a selection plays in a plug-in occurs in the final step; when you are finished processing the pixel region and merge the modified pixel region back into the original drawable, GIMP will use the actual selection (not just its bounds) to mask out the unselected portions of the rectangular pixel region when performing this merge. The masking is done automatically when your plug-in calls 'gimp_drawable_merge_shadow()' (the only way to avoid it is to clear the selection before merging).

Hmmm, typical. The day after I post the link, the page disappears.

Here is a working -- at least for today -- link (though it may be for an older version of GIMP, the information is basically sound):

GIMP plug-in documentation

See It has many links.

One thing it says is, read existing plugins. Which can be found in the gimp source at gimp/plug-ins (for C plugins.) Download the gimp source. Change directory to that plug-ins directory. Then "grep -Ir selection *". That will show you everywhere the word "selection" is used in any file in that directory tree. Similary, there is much source for plugins in Python and Scheme in the gimp source.

I'm sorry there does not seem to be a well-written explanation of selections in GIMP. If you find one, let us know.

saulgoode explained it well in his extensive answer, but for me I would add just one advice: you do not need to care about selections, gimp will take care of that without your participation. I have written couple of C plugins, never cared about selections and selection works. However I noticed buggy behavior with zoomable preview, when area selected on image was not correctly reflected to preview, but final result was OK.

Subscribe to Comments for "C-code or script to retrieve user selected region"