Method: Magick::Image#dispatch

Defined in:

ext/RMagick/rmimage.cpp

#dispatch(x, y, columns, rows, map, float = false) ⇒ Array<Numeric>

Extract pixel data from the image and returns it as an array of pixels. The “x”, “y”, “width” and “height” parameters specify the rectangle to be extracted. The “map” parameter reflects the expected ordering of the pixel array. It can be any combination or order of R = red, G = green, B = blue, A = alpha, C = cyan, Y = yellow, M = magenta, K = black, or I = intensity (for grayscale). If the “float” parameter is specified and true, the pixel data is returned as floating-point numbers in the range [0..1]. By default the pixel data is returned as integers in the range [0..QuantumRange].

Returns an Array of pixel data.

Parameters:

• x (Numeric) —

  The offset of the rectangle from the upper-left corner of the image.

• y (Numeric) —

  The offset of the rectangle from the upper-left corner of the image.

• columns (Numeric) —

  The width of the rectangle.

• rows (Numeric) —

  The height of the rectangle.

• map (String)
• float (Boolean) (defaults to: false)

Returns:

• (Array<Numeric>) —

  an Array of pixel data

# File 'ext/RMagick/rmimage.cpp', line 5667

VALUE
Image_dispatch(int argc, VALUE *argv, VALUE self)
{
    Image *image;
    long x, y;
    unsigned long columns, rows, n, npixels;
    VALUE pixels_ary;
    StorageType stg_type = QuantumPixel;
    char *map;
    size_t mapL;
    MagickBooleanType okay;
    ExceptionInfo *exception;
    volatile union
    {
        Quantum *i;
        double *f;
        void *v;
    } pixels;

    rm_check_destroyed(self);

    if (argc < 5 || argc > 6)
    {
        rb_raise(rb_eArgError, "wrong number of arguments (%d for 5 or 6)", argc);
    }

    x       = NUM2LONG(argv[0]);
    y       = NUM2LONG(argv[1]);
    columns = NUM2ULONG(argv[2]);
    rows    = NUM2ULONG(argv[3]);
    map     = rm_str2cstr(argv[4], &mapL);
    if (argc == 6)
    {
        stg_type = RTEST(argv[5]) ? DoublePixel : QuantumPixel;
    }

    // Compute the size of the pixel array and allocate the memory.
    npixels = columns * rows * mapL;
    pixels.v = stg_type == QuantumPixel ? (void *) ALLOC_N(Quantum, npixels)
               : (void *) ALLOC_N(double, npixels);

    // Create the Ruby array for the pixels. Return this even if ExportImagePixels fails.
    pixels_ary = rb_ary_new();

    TypedData_Get_Struct(self, Image, &rm_image_data_type, image);

    exception = AcquireExceptionInfo();
    GVL_STRUCT_TYPE(ExportImagePixels) args = { image, x, y, columns, rows, map, stg_type, (void *)pixels.v, exception };
    void *ret = CALL_FUNC_WITHOUT_GVL(GVL_FUNC(ExportImagePixels), &args);
    okay = static_cast<MagickBooleanType>(reinterpret_cast<intptr_t &>(ret));

    if (!okay)
    {
        goto exit;
    }

    CHECK_EXCEPTION();

    DestroyExceptionInfo(exception);

    // Convert the pixel data to the appropriate Ruby type
    if (stg_type == QuantumPixel)
    {
        for (n = 0; n < npixels; n++)
        {
            rb_ary_push(pixels_ary, QUANTUM2NUM(pixels.i[n]));
        }
    }
    else
    {
        for (n = 0; n < npixels; n++)
        {
            rb_ary_push(pixels_ary, rb_float_new(pixels.f[n]));
        }
    }

    exit:
    xfree((void *)pixels.v);

    RB_GC_GUARD(pixels_ary);

    return pixels_ary;
}