gimplayer: GIMP Library Reference Manual

## gimplayer gimplayer — Operations on a single layer. |

## Functions

gint32 | gimp_layer_new ()
gint32 | gimp_layer_new_from_drawable ()
gint32 | gimp_layer_new_from_visible ()
gint32 | gimp_layer_new_from_pixbuf ()
gint32 | gimp_layer_new_from_surface ()
gint32 | gimp_layer_group_new ()
gint32 | gimp_layer_copy ()
gboolean | gimp_layer_scale ()
gboolean | gimp_layer_scale_full ()
gboolean | gimp_layer_resize ()
gboolean | gimp_layer_resize_to_image_size ()
gboolean | gimp_layer_translate ()
gboolean | gimp_layer_add_alpha ()
gboolean | gimp_layer_flatten ()
gboolean | gimp_layer_set_offsets ()
gint32 | gimp_layer_create_mask ()
gint32 | gimp_layer_from_mask ()
gint32 | gimp_layer_get_mask ()
gboolean | gimp_layer_add_mask ()
gboolean | gimp_layer_remove_mask ()
gboolean | gimp_layer_is_floating_sel ()
gboolean | gimp_layer_get_lock_alpha ()
gboolean | gimp_layer_set_lock_alpha ()
gboolean | gimp_layer_get_preserve_trans ()
gboolean | gimp_layer_set_preserve_trans ()
gboolean | gimp_layer_get_apply_mask ()
gboolean | gimp_layer_set_apply_mask ()
gboolean | gimp_layer_get_show_mask ()
gboolean | gimp_layer_set_show_mask ()
gboolean | gimp_layer_get_edit_mask ()
gboolean | gimp_layer_set_edit_mask ()
gdouble | gimp_layer_get_opacity ()
gboolean | gimp_layer_set_opacity ()
GimpLayerMode | gimp_layer_get_mode ()
gboolean | gimp_layer_set_mode ()
GimpLayerColorSpace | gimp_layer_get_blend_space ()
gboolean | gimp_layer_set_blend_space ()
GimpLayerColorSpace | gimp_layer_get_composite_space ()
gboolean | gimp_layer_set_composite_space ()
GimpLayerCompositeMode | gimp_layer_get_composite_mode ()
gboolean | gimp_layer_set_composite_mode ()

## Description

Operations on a single layer.

## Functions

### gimp_layer_new ()

    gint32
    gimp_layer_new (gint32 image_ID,
                    const gchar *name,
                    gint width,
                    gint height,
                    GimpImageType type,
                    gdouble opacity,
                    GimpLayerMode mode);

Create a new layer.

This procedure creates a new layer with the specified width, height, and type. Name, opacity, and mode are also supplied parameters. The new layer still needs to be added to the image, as this is not automatic. Add the new layer with the `gimp_image_insert_layer()` command. Other attributes such as layer mask modes, and offsets should be set with explicit procedure calls.

#### Parameters

image_ID | The image to which to add the layer. |
name | The layer name. |
width | The layer width. |
height | The layer height. |
type | The layer type. |
opacity | The layer opacity. |
mode | The layer combination mode. |

#### Returns

The newly created layer.

### gimp_layer_new_from_drawable ()

    gint32
    gimp_layer_new_from_drawable (gint32 drawable_ID,
                                  gint32 dest_image_ID);

Create a new layer by copying an existing drawable.

This procedure creates a new layer as a copy of the specified drawable. The new layer still needs to be added to the image, as this is not automatic. Add the new layer with the `gimp_image_insert_layer()` command. Other attributes such as layer mask modes, and offsets should be set with explicit procedure calls.

#### Parameters

drawable_ID | The source drawable from where the new layer is copied. |
dest_image_ID | The destination image to which to add the layer. |

#### Returns

The newly copied layer.

### gimp_layer_new_from_visible ()

    gint32
    gimp_layer_new_from_visible (gint32 image_ID,
                                 gint32 dest_image_ID,
                                 const gchar *name);

Create a new layer from what is visible in an image.

This procedure creates a new layer from what is visible in the given image. The new layer still needs to be added to the destination image, as this is not automatic. Add the new layer with the `gimp_image_insert_layer()` command. Other attributes such as layer mask modes, and offsets should be set with explicit procedure calls.

#### Parameters

image_ID | The source image from where the content is copied. |
dest_image_ID | The destination image to which to add the layer. |
name | The layer name. |

#### Returns

The newly created layer.

Since: 2.6

### gimp_layer_new_from_pixbuf ()

    gint32
    gimp_layer_new_from_pixbuf (gint32 image_ID,
                                const gchar *name,
                                GdkPixbuf *pixbuf,
                                gdouble opacity,
                                GimpLayerMode mode,
                                gdouble progress_start,
                                gdouble progress_end);

Create a new layer from a `GdkPixbuf`.

This procedure creates a new layer from the given `GdkPixbuf`. The image has to be an RGB image and just like with `gimp_layer_new()` you will still need to add the layer to it.

If you pass `progress_end` > `progress_start` to this function, `gimp_progress_update()` will be called for. You have to call `gimp_progress_init()` beforehand then.

#### Parameters

image_ID | The RGB image to which to add the layer. |
name | The layer name. |
pixbuf | A GdkPixbuf. |
opacity | The layer opacity. |
mode | The layer combination mode. |
progress_start | start of progress |
progress_end | end of progress |

#### Returns

The newly created layer.

Since: 2.4

### gimp_layer_new_from_surface ()

    gint32
    gimp_layer_new_from_surface (gint32 image_ID,
                                 const gchar *name,
                                 cairo_surface_t *surface,
                                 gdouble progress_start,
                                 gdouble progress_end);

Create a new layer from a cairo_surface_t.

This procedure creates a new layer from the given cairo_surface_t. The image has to be an RGB image and just like with `gimp_layer_new()` you will still need to add the layer to it.

If you pass `progress_end` > `progress_start` to this function, `gimp_progress_update()` will be called for. You have to call `gimp_progress_init()` beforehand then.

#### Parameters

image_ID | The RGB image to which to add the layer. |
name | The layer name. |
surface | A Cairo image surface. |
progress_start | start of progress |
progress_end | end of progress |

#### Returns

The newly created layer.

Since: 2.8

### gimp_layer_group_new ()

    gint32
    gimp_layer_group_new (gint32 image_ID);

Create a new layer group.

This procedure creates a new layer group. Attributes such as layer mode and opacity should be set with explicit procedure calls. Add the new layer group (which is a kind of layer) with the `gimp_image_insert_layer()` command. Other procedures useful with layer groups: `gimp_image_reorder_item()`, `gimp_item_get_parent()`, `gimp_item_get_children()`, `gimp_item_is_group()`.

#### Parameters

image_ID | The image to which to add the layer group. |

#### Returns

The newly created layer group.

Since: 2.8

### gimp_layer_copy ()

    gint32
    gimp_layer_copy (gint32 layer_ID);

Copy a layer.

This procedure copies the specified layer and returns the copy. The newly copied layer is for use within the original layer's image. It should not be subsequently added to any other image.

#### Parameters

layer_ID | The layer to copy. |

#### Returns

The newly copied layer.

### gimp_layer_scale ()

    gboolean
    gimp_layer_scale (gint32 layer_ID,
                      gint new_width,
                      gint new_height,
                      gboolean local_origin);

Scale the layer using the default interpolation method.

This procedure scales the layer so that its new width and height are equal to the supplied parameters. The 'local-origin' parameter specifies whether to scale from the center of the layer, or from the image origin. This operation only works if the layer has been added to an image. The interpolation method used can be set with `gimp_context_set_interpolation()`.

#### Parameters

layer_ID | The layer. |
new_width | New layer width. |
new_height | New layer height. |
local_origin | Use a local origin (as opposed to the image origin). |

#### Returns

TRUE on success.

### gimp_layer_scale_full ()

    gboolean
    gimp_layer_scale_full (gint32 layer_ID,
                           gint new_width,
                           gint new_height,
                           gboolean local_origin,
                           GimpInterpolationType interpolation);

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

Use `gimp_layer_scale()` instead.

#### Parameters

layer_ID | The layer. |
new_width | New layer width. |
new_height | New layer height. |
local_origin | Use a local origin (as opposed to the image origin). |
interpolation | Type of interpolation. |

#### Returns

TRUE on success.

Since: 2.6

### gimp_layer_resize ()

    gboolean
    gimp_layer_resize (gint32 layer_ID,
                       gint new_width,
                       gint new_height,
                       gint offx,
                       gint offy);

Resize the layer to the specified extents.

This procedure resizes the layer so that its new width and height are equal to the supplied parameters. Offsets are also provided which describe the position of the previous layer's content. This operation only works if the layer has been added to an image.

#### Parameters

layer_ID | The layer. |
new_width | New layer width. |
new_height | New layer height. |
offx | x offset between upper left corner of old and new layers: (old - new). |
offy | y offset between upper left corner of old and new layers: (old - new). |

#### Returns

TRUE on success.

### gimp_layer_resize_to_image_size ()

    gboolean
    gimp_layer_resize_to_image_size (gint32 layer_ID);

Resize a layer to the image size.

This procedure resizes the layer so that it's new width and height are equal to the width and height of its image container.

#### Parameters

layer_ID | The layer to resize. |

#### Returns

TRUE on success.

### gimp_layer_translate ()

    gboolean
    gimp_layer_translate (gint32 layer_ID,
                          gint offx,
                          gint offy);

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

Use `gimp_item_transform_translate()` instead.

Translate the layer by the specified offsets.

This procedure translates the layer by the amounts specified in the x and y arguments. These can be negative, and are considered offsets from the current position. This command only works if the layer has been added to an image. All additional layers contained in the image which have the linked flag set to TRUE w ill also be translated by the specified offsets.

#### Parameters

layer_ID | The layer. |
offx | Offset in x direction. |
offy | Offset in y direction. |

#### Returns

TRUE on success.

### gimp_layer_add_alpha ()

    gboolean
    gimp_layer_add_alpha (gint32 layer_ID);

Add an alpha channel to the layer if it doesn't already have one.

This procedure adds an additional component to the specified layer if it does not already possess an alpha channel. An alpha channel makes it possible to clear and erase to transparency, instead of the background color. This transforms layers of type RGB to RGBA, GRAY to GRAYA, and INDEXED to INDEXEDA.

#### Parameters

layer_ID | The layer. |

#### Returns

TRUE on success.

### gimp_layer_flatten ()

    gboolean
    gimp_layer_flatten (gint32 layer_ID);

Remove the alpha channel from the layer if it has one.

This procedure removes the alpha channel from a layer, blending all (partially) transparent pixels in the layer against the background color. This transforms layers of type RGBA to RGB, GRAYA to GRAY, and INDEXEDA to INDEXED.

#### Parameters

layer_ID | The layer. |

#### Returns

TRUE on success.

Since: 2.4

### gimp_layer_set_offsets ()

    gboolean
    gimp_layer_set_offsets (gint32 layer_ID,
                            gint offx,
                            gint offy);

Set the layer offsets.

This procedure sets the offsets for the specified layer. The offsets are relative to the image origin and can be any values. This operation is valid only on layers which have been added to an image.

#### Parameters

layer_ID | The layer. |
offx | Offset in x direction. |
offy | Offset in y direction. |

#### Returns

TRUE on success.

### gimp_layer_create_mask ()

    gint32
    gimp_layer_create_mask (gint32 layer_ID,
                            GimpAddMaskType mask_type);

Create a layer mask for the specified layer.

This procedure creates a layer mask for the specified layer. Layer masks serve as an additional alpha channel for a layer. Different types of masks are allowed for initialisation:

- white mask (leaves the layer fully visible);

- black mask (gives the layer complete transparency);

- the layer's alpha channel (either a copy, or a transfer, which leaves the layer fully visible, but which may be more useful than a white mask);

- the current selection;

- a grayscale copy of the layer;

- or a copy of the active channel.

The layer mask still needs to be added to the layer. This can be done with a call to `gimp_layer_add_mask()`.

gimp_layer_create_mask() will fail if there are no active channels on the image, when called with 'ADD-CHANNEL-MASK'. It will return a black mask when called with 'ADD-ALPHA-MASK' or 'ADD-ALPHA-TRANSFER-MASK' on a layer with no alpha channels, or with 'ADD-SELECTION-MASK' when there is no selection on the image.

#### Parameters

layer_ID | The layer to which to add the mask. |
mask_type | The type of mask. |

#### Returns

The newly created mask.

### gimp_layer_from_mask ()

    gint32
    gimp_layer_from_mask (gint32 mask_ID);

Get the specified mask's layer.

This procedure returns the specified mask's layer , or -1 if none exists.

#### Parameters

mask_ID | Mask for which to return the layer. |

#### Returns

The mask's layer.

Since: 2.2

### gimp_layer_get_mask ()

    gint32
    gimp_layer_get_mask (gint32 layer_ID);

Get the specified layer's mask if it exists.

This procedure returns the specified layer's mask, or -1 if none exists.

#### Parameters

layer_ID | The layer. |

#### Returns

The layer mask.

### gimp_layer_add_mask ()

    gboolean
    gimp_layer_add_mask (gint32 layer_ID,
                         gint32 mask_ID);

Add a layer mask to the specified layer.

This procedure adds a layer mask to the specified layer. Layer masks serve as an additional alpha channel for a layer. This procedure will fail if a number of prerequisites aren't met. The layer cannot already have a layer mask. The specified mask must exist and have the same dimensions as the layer. The layer must have been created for use with the specified image and the mask must have been created with the procedure 'gimp-layer-create-mask'.

#### Parameters

layer_ID | The layer to receive the mask. |
mask_ID | The mask to add to the layer. |

#### Returns

TRUE on success.

### gimp_layer_remove_mask ()

    gboolean
    gimp_layer_remove_mask (gint32 layer_ID,
                            GimpMaskApplyMode mode);

Remove the specified layer mask from the layer.

This procedure removes the specified layer mask from the layer. If the mask doesn't exist, an error is returned.

#### Parameters

layer_ID | The layer from which to remove mask. |
mode | Removal mode. |

#### Returns

TRUE on success.

### gimp_layer_is_floating_sel ()

    gboolean
    gimp_layer_is_floating_sel (gint32 layer_ID);

Is the specified layer a floating selection?

This procedure returns whether the layer is a floating selection. Floating selections are special cases of layers which are attached to a specific drawable.

#### Parameters

layer_ID | The layer. |

#### Returns

TRUE if the layer is a floating selection.

### gimp_layer_get_lock_alpha ()

    gboolean
    gimp_layer_get_lock_alpha (gint32 layer_ID);

Get the lock alpha channel setting of the specified layer.

This procedure returns the specified layer's lock alpha channel setting.

#### Parameters

layer_ID | The layer. |

#### Returns

The layer's lock alpha channel setting.

### gimp_layer_set_lock_alpha ()

    gboolean
    gimp_layer_set_lock_alpha (gint32 layer_ID,
                               gboolean lock_alpha);

Set the lock alpha channel setting of the specified layer.

This procedure sets the specified layer's lock alpha channel setting.

#### Parameters

layer_ID | The layer. |
lock_alpha | The new layer's lock alpha channel setting. |

#### Returns

TRUE on success.

### gimp_layer_get_preserve_trans ()

    gboolean
    gimp_layer_get_preserve_trans (gint32 layer_ID);

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

This procedure is deprecated! Use `gimp_layer_get_lock_alpha()` instead.

#### Parameters

layer_ID | The layer. |

#### Returns

The layer's preserve transperancy setting.

### gimp_layer_set_preserve_trans ()

    gboolean
    gimp_layer_set_preserve_trans (gint32 layer_ID,
                                   gboolean preserve_trans);

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

This procedure is deprecated! Use `gimp_layer_set_lock_alpha()` instead.

#### Parameters

layer_ID | The layer. |
preserve_trans | The new layer's preserve transperancy setting. |

#### Returns

TRUE on success.

### gimp_layer_get_apply_mask ()

    gboolean
    gimp_layer_get_apply_mask (gint32 layer_ID);

Get the apply mask setting of the specified layer.

This procedure returns the specified layer's apply mask setting. If the value is TRUE, then the layer mask for this layer is currently being composited with the layer's alpha channel.

#### Parameters

layer_ID | The layer. |

#### Returns

The layer's apply mask setting.

### gimp_layer_set_apply_mask ()

    gboolean
    gimp_layer_set_apply_mask (gint32 layer_ID,
                               gboolean apply_mask);

Set the apply mask setting of the specified layer.

This procedure sets the specified layer's apply mask setting. This controls whether the layer's mask is currently affecting the alpha channel. If there is no layer mask, this function will return an error.

#### Parameters

layer_ID | The layer. |
apply_mask | The new layer's apply mask setting. |

#### Returns

TRUE on success.

### gimp_layer_get_show_mask ()

    gboolean
    gimp_layer_get_show_mask (gint32 layer_ID);

Get the show mask setting of the specified layer.

This procedure returns the specified layer's show mask setting. This controls whether the layer or its mask is visible. TRUE indicates that the mask should be visible. If the layer has no mask, then this function returns an error.

#### Parameters

layer_ID | The layer. |

#### Returns

The layer's show mask setting.

### gimp_layer_set_show_mask ()

    gboolean
    gimp_layer_set_show_mask (gint32 layer_ID,
                              gboolean show_mask);

Set the show mask setting of the specified layer.

This procedure sets the specified layer's show mask setting. This controls whether the layer or its mask is visible. TRUE indicates that the mask should be visible. If there is no layer mask, this function will return an error.

#### Parameters

layer_ID | The layer. |
show_mask | The new layer's show mask setting. |

#### Returns

TRUE on success.

### gimp_layer_get_edit_mask ()

    gboolean
    gimp_layer_get_edit_mask (gint32 layer_ID);

Get the edit mask setting of the specified layer.

This procedure returns the specified layer's edit mask setting. If the value is TRUE, then the layer mask for this layer is currently active, and not the layer.

#### Parameters

layer_ID | The layer. |

#### Returns

The layer's edit mask setting.

### gimp_layer_set_edit_mask ()

    gboolean
    gimp_layer_set_edit_mask (gint32 layer_ID,
                              gboolean edit_mask);

Set the edit mask setting of the specified layer.

This procedure sets the specified layer's edit mask setting. This controls whether the layer or it's mask is currently active for editing. If the specified layer has no layer mask, then this procedure will return an error.

#### Parameters

layer_ID | The layer. |
edit_mask | The new layer's edit mask setting. |

#### Returns

TRUE on success.

### gimp_layer_get_opacity ()

    gdouble
    gimp_layer_get_opacity (gint32 layer_ID);

Get the opacity of the specified layer.

This procedure returns the specified layer's opacity.

#### Parameters

layer_ID | The layer. |

#### Returns

The layer opacity.

### gimp_layer_set_opacity ()

    gboolean
    gimp_layer_set_opacity (gint32 layer_ID,
                            gdouble opacity);

Set the opacity of the specified layer.

This procedure sets the specified layer's opacity.

#### Parameters

layer_ID | The layer. |
opacity | The new layer opacity. |

#### Returns

TRUE on success.

### gimp_layer_get_mode ()

    GimpLayerMode
    gimp_layer_get_mode (gint32 layer_ID);

Get the combination mode of the specified layer.

This procedure returns the specified layer's combination mode.

#### Parameters

layer_ID | The layer. |

#### Returns

The layer combination mode.

### gimp_layer_set_mode ()

    gboolean
    gimp_layer_set_mode (gint32 layer_ID,
                         GimpLayerMode mode);

Set the combination mode of the specified layer.

This procedure sets the specified layer's combination mode.

#### Parameters

layer_ID | The layer. |
mode | The new layer combination mode. |

#### Returns

TRUE on success.

### gimp_layer_get_blend_space ()

    GimpLayerColorSpace
    gimp_layer_get_blend_space (gint32 layer_ID);

Get the blend space of the specified layer.

This procedure returns the specified layer's blend space.

#### Parameters

layer_ID | The layer. |

#### Returns

The layer blend space.

Since: 2.10

### gimp_layer_set_blend_space ()

    gboolean
    gimp_layer_set_blend_space (gint32 layer_ID,
                                GimpLayerColorSpace blend_space);

Set the blend space of the specified layer.

This procedure sets the specified layer's blend space.

#### Parameters

layer_ID | The layer. |
blend_space | The new layer blend space. |

#### Returns

TRUE on success.

Since: 2.10

### gimp_layer_get_composite_space ()

    GimpLayerColorSpace
    gimp_layer_get_composite_space (gint32 layer_ID);

Get the composite space of the specified layer.

This procedure returns the specified layer's composite space.

#### Parameters

layer_ID | The layer. |

#### Returns

The layer composite space.

Since: 2.10

### gimp_layer_set_composite_space ()

    gboolean
    gimp_layer_set_composite_space (gint32 layer_ID,
                                    GimpLayerColorSpace composite_space);

Set the composite space of the specified layer.

This procedure sets the specified layer's composite space.

#### Parameters

layer_ID | The layer. |
composite_space | The new layer composite space. |

#### Returns

TRUE on success.

Since: 2.10

### gimp_layer_get_composite_mode ()

    GimpLayerCompositeMode
    gimp_layer_get_composite_mode (gint32 layer_ID);

Get the composite mode of the specified layer.

This procedure returns the specified layer's composite mode.

#### Parameters

layer_ID | The layer. |

#### Returns

The layer composite mode.

Since: 2.10

### gimp_layer_set_composite_mode ()

    gboolean
    gimp_layer_set_composite_mode (gint32 layer_ID,
                                   GimpLayerCompositeMode composite_mode);

Set the composite mode of the specified layer.

This procedure sets the specified layer's composite mode.

#### Parameters

layer_ID | The layer. |
composite_mode | The new layer composite mode. |

#### Returns

TRUE on success.

Since: 2.10