libvips/doc/binding.xml

95 lines
3.2 KiB
XML

<?xml version="1.0"?>
<!-- vim: set ts=2 sw=2 expandtab: -->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<refentry id="binding">
<refmeta>
<refentrytitle>Writing bindings for libvips</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>VIPS Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Binding</refname>
<refpurpose>How to write bindings for libvips</refpurpose>
</refnamediv>
<refsect3 id="binding-goi">
<title>Binding and gobject-introspection</title>
<para>
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:
<programlisting language="Python">
from gi.repository import Vips
</programlisting>
</para>
<para>
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>
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.
</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:
<programlisting language="bash">
$ g-ir-doc-tool --language=Python -o ~/mydocs Vips-8.0.gir
</programlisting>
Then to view them, either:
<programlisting language="bash">
$ yelp ~/mydocs
</programlisting>
Or perhaps
<programlisting language="bash">
$ cd ~/mydocs
$ yelp-build html .
</programlisting>
To make HTML docs. This is an easy way to see what you can call in the
library.
</para>
</refsect3>
</refentry>