New API takes shape

libvips has had the same interface for C programmers since 1990, with just a few additions. We've been trying to make a fresh start for a while and it seems to be finally happening.

The current development version has a new core rebuilt on top of GObject. Everything is stripped down, cleaned up and much more consistent. All types are created and destroyed with the same few functions, we have reference-counting everywhere (so object lifetime management is mostly automatic), and VipsObject includes a simple layer which adds full runtime introspection (so all interfaces to libvips can always present all the available features).

The old, busted IMAGE and REGION types have become the fresh, new VipsImage and VipsRegion classes. Like all GObject classes, you create them with g_object_new() (or a convenience function, like vips_image_new_from_file()) and unreference them when you're done with g_object_unref().

Image-processing operations, like "add image1 to image2", are also classes. You run them with on images with something like:

vips_operation_new ("add", image1, image2, out, NULL);

Where the NULL marks the end of a list of name / values pairs listing optional arguments defined by VipsAdd or one of its superclasses.

Internally, vips_operation_new() searches the class hierarchy below VipsOperation for a class whose nickname is "add", makes an instance of that class with g_object_new(), loops over the required construct-time properties setting them from the arguments to the C function, then loops over the rest of the C args up to the NULL setting optional named construct-time properties.

Sadly there's therefore no type safety. So there's also a convenience function:

int vips_add (VipsImage *in1, VipsImage in2, VipsImage *out, ...);

And a macro which provides vips7 compatibility:

#define im_add(IN1, IN2, OUT) (vips_add(IN1, IN2, OUT, NULL))

The Python binding works at the vips_operation_new() level and overrides ".", so you can write:

out = image1.add (image2)

and it turns into the call to vips_operation_new() above. Since almost the whole Python binding is generated at runtime, it's very small and will adapt automatically as new operations are added.

So far only one operation has been redone in the new API. The other 299 are all there and working via a set of macros which implement the old vips7 API on top of the shiny new vips8 one. The vips7 compatibility macros are good enough that nip2 also works on the new system with no changes.

The next stable release, due rather soon now, will include this new core. We see vips8 as emerging slowly over the next year or so as, one by one, the old vips7 operators are moved to the new API. When everything is swapped over, we'll document the new API, bump the version number to vips-8.0, and have a large party.