<?xml version="1.0"?>
<page id="Gimp.Layer.create_mask"
      type="topic"
      style="method"
      xmlns="http://projectmallard.org/1.0/"
      xmlns:api="http://projectmallard.org/experimental/api/"
      xmlns:ui="http://projectmallard.org/1.0/ui/">
  <info>
    <link xref="Gimp.Layer" group="method" type="guide"/>
    <api:function>
      <api:returns>
        <api:type>Gimp.LayerMask</api:type>
      </api:returns>
      <api:name>gimp_layer_create_mask</api:name>
      <api:arg>
        <api:type>Gimp.Layer</api:type>
        <api:name>self</api:name>
      </api:arg>
      <api:arg>
        <api:type>Gimp.AddMaskType</api:type>
        <api:name>mask_type</api:name>
      </api:arg>
    </api:function>
  </info>
  <title>Gimp.Layer.create_mask</title>
  <synopsis><code mime="text/x-python">
@accepts(Gimp.Layer, Gimp.AddMaskType)
@returns(Gimp.LayerMask)
def create_mask(self, mask_type):
    # Python wrapper for gimp_layer_create_mask()
  </code></synopsis>
  <p>Create a layer mask for the specified layer.</p>  <p>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.</p>  <p>The layer mask still needs to be added to the layer. This can be
done with a call to <link xref="Gimp.Layer.add_mask"/>.</p>  <p><link xref="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.</p>

<terms>
<item>
<title><code>self</code></title>
  <p>The layer to which to add the mask.</p>
</item>
<item>
<title><code>mask_type</code></title>
  <p>The type of mask.</p>
</item>
<item>
<title><code>Returns</code></title>
{formatter.format(node, node.retval.doc)}
</item>
</terms>

</page>
