manpagez: man pages & more
html files: libvips
Home | html | info | man

Writing bindings for libvips

Binding — How to write bindings for libvips

Binding and gobject-introspection

The C source code to libvips has been marked up with special comments describing the interface in a standard way. These comments are read by gobject-introspection when libvips is compiled and used to generate a typelib, a description of how to call the library. Many languages have gobject-introspection packages: all you need to do to call libvips from your favorite language is to start g-o-i, load the libvips typelib, and you should have the whole library available. For example, from Python it's as simple as:

from gi.repository import Vips

libvips used in this way is likely to be rather bare-bones. For Python, we wrote a set of overrides which layer a more Pythonesque interface on top of the one provided for libvips by pygobject. These overrides are simply a set of Python classes.

To call a vips operation, you'll need to make a new operation with vips_operation_new() (all it does is look up the operation by name with vips_type_find(), then call g_object_new() for you), then use vips_argument_map() and friends to loop over the operation's arguments setting them. Once you have set all arguments, use vips_cache_operation_build() to look up the operation in the cache and either build or dup it. If something goes wrong, you'll need to use vips_object_unref_outputs() and g_object_unref() to free the partially-built object. The Python binding uses this technique to implement a function which can call any vips operation, turning optional vips arguments into Python keyword arguments.

If your language does not have a gobject-introspection package, you'll need to write something in C or C++ doing approximately the same thing. The C++ API takes this route.

You can generate searchable docs from a .gir (the thing that is built from scanning libvips and which in turn turn the typelib is made from) with g-ir-doc-tool, for example:

$ g-ir-doc-tool --language=Python -o ~/mydocs Vips-8.0.gir

Then to view them, either:

$ yelp ~/mydocs 

Or perhaps

$ cd ~/mydocs 
$ yelp-build html .

To make HTML docs. This is an easy way to see what you can call in the library.

© 2000-2018
Individual documents may contain additional copyright information.