2.4 The VIPS base class: VipsObject

VIPS is in the process of moving to an object system based on GObject. You can read about the GObjec library at the GTK+ website:

We’ve implemented two new subsystems (VipsFormat and VipsInterpolate) on top of VipsObject but not yet moved the core VIPS types over. As a result, VipsObject is still developing and is likely to change in the next release.

This section quickly summarises enough of the VipsObject system to let you use the two derived APIs but that’s all. Full documentation will come when this system stabilises.

2.4.1 Properties

Like the rest of VIPS, VipsObject is a functional type. You can set properties during object construction, but not after that point. You may read properties at any time after construction, but not before.

To enforce these rules, VIPS extends the standard GObject property system and adds a new phase to object creation. An object has the following stages in its life:

Lookup

vips_type_find() is a convenience function that looks up a type by its nickname relative to a base class. For example:

finds a subclass of VipsInterpolate nicknamed ‘bilinear’. You can look up types by their full name of course, but these can be rather unwieldy (VipsInterpolateBilinear in this case, for example).

Create

Build an instance with g_object_new(). For example:

You can set any of the object’s properties in the constructor. You can continue to set, but not read, any other properties, for example:

You can loop over an object’s required and optional parameters with vips_argument_map().

Build

Once all of the required any any of the optional object parameters have been set, call vips_object_build():

This function checks that all the parameters have been set correctly and starts the object working. It returns non-zero on error, setting im_error_string().

Use

The object is now fully working. You can read results from it, or pass it on other objects. When you’re finished with it, drop your reference to end its life.

2.4.2 Convenience functions

Two functions simplify building and printing objects. vips_object_new_from_string() makes a new object which is a subclass of a named base class.

This is the function used by IM_INPUT_INTERPOLATE(), for example, to parse command-line arguments. The syntax is:

So values for all the required arguments, in the correct order, then name = value for all the optional arguments you want to set. Parameters may be enclosed in round or curly braces.

vips_object_to_string() is the exact opposite: it generates the construct string for any constructed VipsObject.

vips_object_new() wraps up the business of creating and checking an object. It makes the object, uses the supplied function to attach any arguments, then builds the object and returns NULL on failure or the new object on success.

A switch to the vips command-line program is handy for listing subtypes of VipsObject. Try: