VipsOperation

An abstract base class for all operations in libvips.

It builds on VipsObject to provide the introspection and command-line interface to libvips.

It also maintains a cache of recent operations. See below.

vips_call(), vips_call_split() and vips_call_split_option_string() are used by vips to implement the C API. They can execute any VipsOperation, passing in a set of required and optional arguments. Normally you would not use these functions directly: every operation has a tiny wrapper function which provides type-safety for the required arguments. For example, vips_embed() is defined as:

int
vips_embed(VipsImage *in, VipsImage **out,
    int x, int y, int width, int height, ...)
{
    va_list ap;
    int result;

    va_start(ap, height);
    result = vips_call_split("embed", ap, in, out, x, y, width, height);
    va_end(ap);

    return result;
}

Use vips_call_argv() to run any libvips operation from a command-line style argc/argv array. This is the thing used by the vips main program to implement the command-line interface.

VipsOperation and reference counting

After calling a VipsOperation you are responsible for unreffing any output objects. For example, consider:

VipsImage *im = ...;
VipsImage *t1;

if (vips_invert(im, &t1, NULL))
    error ..

This will invert im and return a new VipsImage, t1. As the caller of vips_invert(), you are responsible for t1 and must unref it when you no longer need it. If vips_invert() fails, no t1 is returned and you don’t need to do anything.

If you don’t need to use im for another operation, you can unref im immediately after the call. If im is needed to calculate t1, vips_invert() will add a ref to im and automatically drop it when t1 is unreffed.

Consider running two operations, one after the other. You could write:

VipsImage *im = ...;
VipsImage *t1, *t2;

if (vips_invert(im, &t1, NULL)) {
    g_object_unref(im);
    return -1;
}
g_object_unref(im);

if (vips_flip(t1, &t2, VIPS_DIRECTION_HORIZONTAL, NULL)) {
    g_object_unref(t1);
    return -1;
}
g_object_unref(t1);

This is correct, but rather long-winded. libvips provides a handy thing to make a vector of auto-freeing object references. You can write this as:

VipsObject *parent = ...;
VipsImage *im = ...;
VipsImage *t = (VipsImage **) vips_object_local_array(parent, 2);

if (vips_invert(im, &t[0], NULL) ||
    vips_flip(t[0], &t[1], VIPS_DIRECTION_HORIZONTAL, NULL))
  return -1;

where parent is some enclosing object which will be unreffed when this task is complete. vips_object_local_array() makes an array of VipsObject (or VipsImage, in this case) where when parent is freed, all non-NULL VipsObject in the array are also unreffed.

The VipsOperation cache

Because all VipsObject are immutable, they can be cached. The cache is very simple to use: instead of calling vips_object_build(), call vips_cache_operation_build(). This function calculates a hash from the operations’ input arguments and looks it up in table of all recent operations. If there’s a hit, the new operation is unreffed, the old operation reffed, and the old operation returned in place of the new one.

The cache size is controlled with vips_cache_set_max() and friends.