gimppixelrgn: GIMP Library Reference Manual

## gimppixelrgn gimppixelrgn — Functions for operating on pixel regions. |

## Functions

void | gimp_pixel_rgn_init ()
void | gimp_pixel_rgn_resize ()
void | gimp_pixel_rgn_get_pixel ()
void | gimp_pixel_rgn_get_row ()
void | gimp_pixel_rgn_get_col ()
void | gimp_pixel_rgn_get_rect ()
void | gimp_pixel_rgn_set_pixel ()
void | gimp_pixel_rgn_set_row ()
void | gimp_pixel_rgn_set_col ()
void | gimp_pixel_rgn_set_rect ()
gpointer | gimp_pixel_rgns_register ()
gpointer | gimp_pixel_rgns_register2 ()
gpointer | gimp_pixel_rgns_process ()

## Types and Values

| GimpPixelRgn

## Description

Functions for operating on pixel regions. These functions provide fast ways of accessing and modifying portions of a drawable.

## Functions

### gimp_pixel_rgn_init ()

    void
    gimp_pixel_rgn_init (GimpPixelRgn *pr,
                         GimpDrawable *drawable,
                         gint x,
                         gint y,
                         gint width,
                         gint height,
                         gint dirty,
                         gint shadow);

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

Initialize the pixel region pointed by `pr` with the specified parameters.

The `dirty` and `shadow` flags can be used as follows:

- `dirty` = FALSE, `shadow` = FALSE: the region will be used to read the actual drawable datas. This is useful for save plug-ins or for filters.

- `dirty` = FALSE, `shadow` = TRUE: the region will be used to read the shadow tiles. This is used in some filter plug-ins which operate in two passes such as gaussian blur. The first pass reads the actual drawable data and writes to the shadow tiles, and the second one reads from and writes to the shadow tiles.

- `dirty` = TRUE, `shadow` = TRUE: the region will be used to write to the shadow tiles. It is common practice to write to the shadow tiles and then use `gimp_drawable_merge_shadow()` to merge the changes from the shadow tiles using the current selection as a mask.

- `dirty` = TRUE, `shadow` = FALSE: the region will be used to directly change the drawable content. Don't do this, since this could prevent the Undo-System from working as expected.

#### Parameters

pr | a pointer to a GimpPixelRgn variable. |
drawable | the GimpDrawable the new region will be attached to. |
x | the x coordinate of the top-left pixel of the region in the `drawable` . |
y | the y coordinate of the top-left pixel of the region in the `drawable` . |
width | the width of the region. |
height | the height of the region. |
dirty | a gboolean indicating whether the `drawable` should be marked as "dirty". |
shadow | a gboolean indicating whether the region is attached to the shadow tiles or the real `drawable` tiles. |

### gimp_pixel_rgn_resize ()

    void
    gimp_pixel_rgn_resize (GimpPixelRgn *pr,
                           gint x,
                           gint y,
                           gint width,
                           gint height);

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

Change the position and size of a previously initialized pixel region.

#### Parameters

pr | a pointer to a previously initialized GimpPixelRgn. |
x | the x coordinate of the new position of the region's top-left corner. |
y | the y coordinate of the new position of the region's top-left corner. |
width | the new width of the region. |
height | the new height of the region. |

### gimp_pixel_rgn_get_pixel ()

    void
    gimp_pixel_rgn_get_pixel (GimpPixelRgn *pr,
                              guchar *buf,
                              gint x,
                              gint y);

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

Fill the buffer pointed by `buf` with the value of the pixel at (`x` , `y` ) in the region `pr` . `buf` should be large enough to hold the pixel value (1 guchar for an indexed or grayscale drawable, 2 guchar for indexed with alpha or grayscale with alpha drawable, 3 guchar for rgb drawable and 4 guchar for rgb with alpha drawable.

#### Parameters

pr | a pointer to a previously initialized GimpPixelRgn. |
buf | a pointer to an array of guchar |
x | the x coordinate of the wanted pixel (relative to the drawable) |
y | the y coordinate of the wanted pixel (relative to the drawable) |

### gimp_pixel_rgn_get_row ()

    void
    gimp_pixel_rgn_get_row (GimpPixelRgn *pr,
                            guchar *buf,
                            gint x,
                            gint y,
                            gint width);

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

Get several pixels of a region in a row. This function fills the buffer `buf` with the values of the pixels from (`x` , `y` ) to (`x` +`width` -1, `y` ). `buf` should be large enough to hold all these values.

#### Parameters

pr | a pointer to a previously initialized GimpPixelRgn. |
buf | a pointer to an array of guchar |
x | the x coordinate of the first pixel (relative to the drawable). |
y | the y coordinate of the first pixel (relative to the drawable). |
width | the number of pixels to get. |

### gimp_pixel_rgn_get_col ()

    void
    gimp_pixel_rgn_get_col (GimpPixelRgn *pr,
                            guchar *buf,
                            gint x,
                            gint y,
                            gint height);

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

Get several pixels of a region's column. This function fills the buffer `buf` with the values of the pixels from (`x` , `y` ) to (`x` , `y` +`height` -1). `buf` should be large enough to hold all these values.

#### Parameters

pr | a pointer to a previously initialized GimpPixelRgn. |
buf | a pointer to an array of guchar |
x | the x coordinate of the first pixel (relative to the drawable). |
y | the y coordinate of the first pixel (relative to the drawable). |
height | the number of pixels to get. |

### gimp_pixel_rgn_get_rect ()

    void
    gimp_pixel_rgn_get_rect (GimpPixelRgn *pr,
                             guchar *buf,
                             gint x,
                             gint y,
                             gint width,
                             gint height);

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

Get all the pixel values from the rectangle defined by `x` , `y` , `width` and `height` . This function fills the buffer `buf` with the values of the pixels from (`x` , `y` ) to (`x` +`width` -1, `y` +`height` -1). `buf` should be large enough to hold all these values (`width` *`height` *bpp).

#### Parameters

pr | a pointer to a previously initialized GimpPixelRgn. |
buf | a pointer to an array of guchar |
x | the x coordinate of the first pixel (relative to the drawable). |
y | the y coordinate of the first pixel (relative to the drawable). |
width | the width of the rectangle. |
height | the height of the rectangle. |

### gimp_pixel_rgn_set_pixel ()

    void
    gimp_pixel_rgn_set_pixel (GimpPixelRgn *pr,
                              const guchar *buf,
                              gint x,
                              gint y);

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

Set the pixel at (`x` , `y` ) to the values from `buf` .

#### Parameters

pr | a pointer to a previously initialized GimpPixelRgn. |
buf | a pointer to an array of guchar. |
x | the x coordinate of the pixel (relative to the drawable). |
y | the y coordinate of the pixel (relative to the drawable). |

### gimp_pixel_rgn_set_row ()

    void
    gimp_pixel_rgn_set_row (GimpPixelRgn *pr,
                            const guchar *buf,
                            gint x,
                            gint y,
                            gint width);

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

Set several pixels of a region in a row. This function draws the pixels from (`x` , `y` ) to (`x` +`width` -1, `y` ) using the values of the buffer `buf` . `buf` should be large enough to hold all these values.

#### Parameters

pr | a pointer to a previously initialized GimpPixelRgn. |
buf | a pointer to an array of guchar |
x | the x coordinate of the first pixel (relative to the drawable). |
y | the y coordinate of the first pixel (relative to the drawable). |
width | the number of pixels to set. |

### gimp_pixel_rgn_set_col ()

    void
    gimp_pixel_rgn_set_col (GimpPixelRgn *pr,
                            const guchar *buf,
                            gint x,
                            gint y,
                            gint height);

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

Set several pixels of a region's column. This function draws the pixels from (`x` , `y` ) to (`x` , `y` +`height` -1) using the values from the buffer `buf` . `buf` should be large enough to hold all these values.

#### Parameters

pr | a pointer to a previously initialized GimpPixelRgn. |
buf | a pointer to an array of guchar |
x | the x coordinate of the first pixel (relative to the drawable). |
y | the y coordinate of the first pixel (relative to the drawable). |
height | the number of pixels to set. |

### gimp_pixel_rgn_set_rect ()

    void
    gimp_pixel_rgn_set_rect (GimpPixelRgn *pr,
                             const guchar *buf,
                             gint x,
                             gint y,
                             gint width,
                             gint height);

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

Set all the pixel of the rectangle defined by `x` , `y` , `width` and `height` . This function draws the rectangle from (`x` , `y` ) to (`x` +`width` -1, `y` +`height` -1), using the pixel values from the buffer `buf` . `buf` should be large enough to hold all these values (`width` *`height` *bpp).

#### Parameters

pr | a pointer to a previously initialized GimpPixelRgn. |
buf | a pointer to an array of guchar |
x | the x coordinate of the first pixel (relative to the drawable). |
y | the y coordinate of the first pixel (relative to the drawable). |
width | the width of the rectangle. |
height | the height of the rectangle. |

### gimp_pixel_rgns_register ()

    gpointer
    gimp_pixel_rgns_register (gint nrgns,
                              ...);

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

This is the varargs version of gimp_pixel_rgns_register2.

#### Parameters

nrgns | the number of regions to register. |
... | `nrgns` pointers to GimpPixelRgn. |

#### Returns

a gpointer to a regions iterator.

### gimp_pixel_rgns_register2 ()

    gpointer
    gimp_pixel_rgns_register2 (gint nrgns,
                               GimpPixelRgn **prs);

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

It takes a number of initialized regions of the same size and provides a pixel region iterator the iterator can be used to iterate over the registered pixel regions. While iterating the registered pixel regions will cover subsets of the original pixel regions, chosen for optimized access to the image data.

Note that the given regions themselves are changed by this function, so they are resized to the first subsets.

This function has to be used together with gimp_pixel_rgns_process in a loop.

#### Parameters

nrgns | the number of regions to register. |
prs | an array of `nrgns` pointers to initialized GimpPixelRgn. |

#### Returns

a gpointer to a regions iterator.

### gimp_pixel_rgns_process ()

    gpointer
    gimp_pixel_rgns_process (gpointer pri_ptr);

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

This function update the regions registered previously with one of the gimp_pixel_rgns_register* functions to their next tile.

#### Parameters

pri_ptr | a regions iterator returned by gimp_pixel_rgns_register, gimp_pixel_rgns_register2 or gimp_pixel_rgns_process. |

#### Returns

a gpointer to a new regions iterator or NULL if there isn't any tiles left.

## Types and Values

### GimpPixelRgn

    typedef struct {
      guchar       *data;          /* pointer to region data */
      GimpDrawable *drawable;      /* pointer to drawable */
      gint          bpp;           /* bytes per pixel */
      gint          rowstride;     /* bytes per pixel row */
      gint          x, y;          /* origin */
      gint          w, h;          /* width and height of region */
      guint         dirty : 1;     /* will this region be dirtied? */
      guint         shadow : 1;    /* will this region use the shadow or normal tiles */
      gint          process_count; /* used internally */
    } GimpPixelRgn;