<refmeta><refentrytitle>How to write bindings</refentrytitle><manvolnum>3</manvolnum><refmiscinfo>libvips</refmiscinfo></refmeta>
</para>
<para>
<refnamediv><refname>Binding</refname><refpurpose>Writing bindings for libvips</refpurpose></refnamediv>
</para>
<para>
There are full libvips bindings for quite a few languages now: C, C++, Ruby, PHP, Python and JavaScript.
</para>
<para>
This chapter runs through the four main styles that have been found to work well. If you want to write a new binding, one of these should be close to what you need.
</para>
<refsect3id="c-api">
<title>C API</title>
<para>
The libvips C API (vips_add() and so on) is very inconvenient to use from other languages due to its heavy use of varargs.
</para>
<para>
It’s much better to use the layer below. This lower layer is structured as: create operator, set parameters, execute, extract results. For example, you can execute vips_invert() like this:
libvips has a couple of extra things to let you fetch the arguments and types of an operator. Use vips_lib.vips_argument_map() to loop over all the arguments of an operator, and vips_object_get_argument() to fetch the type and flags of a specific argument.
</para>
<para>
Use vips_operation_get_flags() to get general information about an operator.
</para>
</refsect3>
<refsect3id="compiled-language-which-can-call-c">
<title>Compiled language which can call C</title>
<para>
The C++ binding uses this lower layer to define a function called <literal>VImage::call()</literal> which can call any libvips operator with a not-varargs set of variable arguments.
</para>
<para>
A small Python program walks the set of all libvips operators and generates a set of static bindings. For example:
So from C++ you can call any libvips operator, though without type-safety, with <literal>VImage::call()</literal>, or use the member functions on <literal>VImage</literal> to get type-safe calls for at least the required operator arguments.
</para>
<para>
The <literal>VImage</literal> class also adds automatic reference counting, constant expansion, operator overloads, and various other useful features.
</para>
</refsect3>
<refsect3id="dynamic-language-with-ffi">
<title>Dynamic language with FFI</title>
<para>
Languages like Ruby, Python, JavaScript and Lua can’t call C directly, but they do support FFI. The bindings for these languages work rather like C++, but use FFI to call into libvips and run operations.
</para>
<para>
Since these languages are dynamic, they can add another trick: they intercept the method-missing hook and attempt to run any method calls not implemented by the <literal>Image</literal> class as libvips operators. This makes these bindings self-writing: they only contain a small amount of codeand just expose everything they find in the libvips class hierarchy.
</para>
</refsect3>
<refsect3id="dynamic-langauge-without-ffi">
<title>Dynamic langauge without FFI</title>
<para>
PHP does not have FFI, unfortunately, so for this language a small native module implements the general <literal>vips_call()</literal> function for PHP language types, and a larger pure PHP layer makes it convenient to use.
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 the <literal>gobject-introspection</literal> package 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:
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.
</para>
<para>
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.
</para>
<para>
You can generate searchable docs from a <code>.gir</code> (the thing that is built from scanning libvips and which in turn turn the typelib is made from) with <command>g-ir-doc-tool</command>, for example:
