Method: Magick::Image#mask

Defined in:

ext/RMagick/rmimage.c

#mask(*args) ⇒ Object

Associate a clip mask with the image.

Ruby usage:

- @verbatim Image#mask @endverbatim
- @verbatim Image#mask(mask-image) @endverbatim

Notes:

- Omit the argument to get a copy of the current clip mask.
- Pass "nil" for the mask-image to remove the current clip mask.
- If the clip mask is not the same size as the target image, resizes the
  clip mask to match the target.
- Distinguish from Image#clip_mask=

Parameters:

• argc —

  number of input arguments

• argv —

  array of input arguments

• self —

  this object

Returns:

• copy of the current clip-mask or nil

See Also:

• get_image_mask

# File 'ext/RMagick/rmimage.c', line 8330

VALUE
Image_mask(int argc, VALUE *argv, VALUE self)
{
    volatile VALUE mask;
    Image *image, *mask_image, *resized_image;
    Image *clip_mask;
    long x, y;
    PixelPacket *q;
    ExceptionInfo exception;

    image = rm_check_destroyed(self);
    if (argc == 0)
    {
        return get_image_mask(image);
    }
    if (argc > 1)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (expected 0 or 1, got %d)", argc);
    }

    rb_check_frozen(self);
    mask = argv[0];

    if (mask != Qnil)
    {
        mask = rm_cur_image(mask);
        mask_image = rm_check_destroyed(mask);
        clip_mask = rm_clone_image(mask_image);

        // Resize if necessary
        if (clip_mask->columns != image->columns || clip_mask->rows != image->rows)
        {
            GetExceptionInfo(&exception);
            resized_image = ResizeImage(clip_mask, image->columns, image->rows
                                        , UndefinedFilter, 0.0, &exception);
            rm_check_exception(&exception, resized_image, DestroyOnError);
            (void) DestroyExceptionInfo(&exception);
            rm_ensure_result(resized_image);
            (void) DestroyImage(clip_mask);
            clip_mask = resized_image;
        }

        // The following section is copied from mogrify.c (6.2.8-8)
#if defined(HAVE_SYNCAUTHENTICPIXELS)
        GetExceptionInfo(&exception);
#endif
        for (y = 0; y < (long) clip_mask->rows; y++)
        {
#if defined(HAVE_GETAUTHENTICPIXELS)
            q = GetAuthenticPixels(clip_mask, 0, y, clip_mask->columns, 1, &exception);
            rm_check_exception(&exception, clip_mask, DestroyOnError);
#else
            q = GetImagePixels(clip_mask, 0, y, clip_mask->columns, 1);
            rm_check_image_exception(clip_mask, DestroyOnError);
#endif
            if (!q)
            {
                break;
            }
            for (x = 0; x < (long) clip_mask->columns; x++)
            {
                if (clip_mask->matte == MagickFalse)
                {
                    q->opacity = PIXEL_INTENSITY(q);
                }
                q->red = q->opacity;
                q->green = q->opacity;
                q->blue = q->opacity;
                q += 1;
            }

#if defined(HAVE_SYNCAUTHENTICPIXELS)
            SyncAuthenticPixels(clip_mask, &exception);
            rm_check_exception(&exception, clip_mask, DestroyOnError);
#else
            SyncImagePixels(clip_mask);
            rm_check_image_exception(clip_mask, DestroyOnError);
#endif
        }
#if defined(HAVE_SYNCAUTHENTICPIXELS)
        (void) DestroyExceptionInfo(&exception);
#endif

        SetImageStorageClass(clip_mask, DirectClass);
        rm_check_image_exception(clip_mask, DestroyOnError);

        clip_mask->matte = MagickTrue;

        // SetImageClipMask clones the clip_mask image. We can
        // destroy our copy after SetImageClipMask is done with it.

        (void) SetImageClipMask(image, clip_mask);
        (void) DestroyImage(clip_mask);
    }
    else
    {
        (void) SetImageClipMask(image, NULL);
    }

    // Always return a copy of the mask!
    return get_image_mask(image);
}