"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "doc/binding.md" between
vips-8.10.6.tar.gz and vips-8.11.0.tar.gz

About: VIPS is a free image processing system (see also the GUI nip2).

binding.md  (vips-8.10.6):binding.md  (vips-8.11.0)
skipping to change at line 21 skipping to change at line 21
There are full libvips bindings for quite a few environments now: C, C++, There are full libvips bindings for quite a few environments now: C, C++,
command-line, Ruby, PHP, Lua, Python and JavaScript (node). command-line, Ruby, PHP, Lua, Python and JavaScript (node).
This chapter runs through the four main styles that have been found to work 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 well. If you want to write a new binding, one of these should be close
to what you need. to what you need.
# Don't bind the top-level C API # Don't bind the top-level C API
The libvips C API (vips_add() and so on) is very inconvenient and dangerous The libvips C API (vips_add() and so on) was designed to be easy for humans
to use from other languages due to its heavy use of varargs. to write. It is inconvenient and dangerous to use from other languages due
to its heavy use of varargs.
It's much better to use the layer below. This lower layer is structured as 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: - Create operator. You can use vips_operation_new() to make a new
`VipsOperation` object from an operator nickname, like `"add"`.
- Set parameters. You can loop over the operation with vips_argument_map() to
get the name and type of each input argument. For each argument, you
need to get the value from your language, convert to a `GValue`, then
use g_object_set_property() to set that value on the operator.
- Execute with vips_cache_operation_build().
- Extract results. Again, you loop over the operator arguments with
vips_argument_map(), but instead of inputs, this time you look for output
arguments. You extract their value with g_object_get_property(), and pass
the value back to your language.
For example, you can execute vips_invert() like this:
```C ```C
/* compile with /* compile with
* *
* gcc -g -Wall callvips.c `pkg-config vips --cflags --libs` * gcc -g -Wall callvips.c `pkg-config vips --cflags --libs`
* *
*/ */
#include <vips/vips.h> #include <vips/vips.h>
skipping to change at line 116 skipping to change at line 132
if( vips_image_write_to_file( out, argv[2], NULL ) ) if( vips_image_write_to_file( out, argv[2], NULL ) )
vips_error_exit( NULL ); vips_error_exit( NULL );
g_object_unref( out ); g_object_unref( out );
return( 0 ); return( 0 );
} }
``` ```
libvips has a couple of extra things to let you examine the arguments and
types of an operator at runtime. Use 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.
Use vips_operation_get_flags() to get general information about an operator.
# Compiled language which can call C # Compiled language which can call C
The C++ binding uses this lower layer to define a function called The C++ binding uses this lower layer to define a function called
`VImage::call()` which can call any libvips operator with a not-varargs set of `VImage::call()` which can call any libvips operator with a set of variable
variable arguments. arguments.
A small Python program walks the set of all libvips operators and generates a A small Python program walks the set of all libvips operators and generates a
set of static bindings. For example: set of static bindings. For example:
```c++ ```c++
VImage VImage::invert( VOption *options ) VImage VImage::invert( VOption *options )
{ {
VImage out; VImage out;
call( "invert", (options ? options : VImage::option()) -> call( "invert", (options ? options : VImage::option()) ->
set( "in", *this ) -> set( "in", *this ) ->
set( "out", &out ) ); set( "out", &out ) );
return( out ); return( out );
} }
``` ```
So from C++ you can call any libvips operator (though without type-safety) with So from C++ you can call any libvips operator (though without static
`VImage::call()`, or use the member functions on `VImage` to get type-safe typechecking) with `VImage::call()`, or use the member functions on `VImage`
calls for at least the required operator arguments. to get type-checked calls for at least the required operator arguments.
The `VImage` class also adds automatic reference counting, constant expansion, The `VImage` class also adds automatic reference counting, constant expansion,
operator overloads, and various other useful features. operator overloads, and various other useful features.
# Dynamic language with FFI # Dynamic language with FFI
Languages like Ruby, Python, JavaScript and LuaJIT can't call C directly, but Languages like Ruby, Python, JavaScript and LuaJIT can't call C directly, but
they do support FFI. The bindings for these languages work rather like C++, they do support FFI. The bindings for these languages work rather like C++,
but use FFI to call into libvips and run operations. but use FFI to call into libvips and run operations.
Since these languages are dynamic, they can add another trick: they intercept 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 method-missing hook and attempt to run any method calls not implemented by
the `Image` class as libvips operators. This makes these bindings self-writing: the `Image` class as libvips operators. In effect, the binding is generated at
they only contain a small amount of code and just expose everything they find in runtime.
the libvips class hierarchy.
# Dynamic langauge without FFI # Dynamic langauge without FFI
PHP does not have FFI, unfortunately, so for this language a small native PHP does not have a useful FFI, unfortunately, so for this language a small
module implements the general `vips_call()` function for PHP language types, C module implements the general `vips_call()` function for PHP language
and a larger pure PHP layer makes it convenient to use. types, and a larger pure PHP layer makes it convenient to use.
# gobject-introspection # gobject-introspection
The C source code to libvips has been marked up with special comments 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 describing the interface in a standard way. These comments are read by
the `gobject-introspection` package when libvips is compiled and used to the `gobject-introspection` package when libvips is compiled and used to
generate a typelib, a description of how to call the library. Many languages 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 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, 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 and you should have the whole library available. For example, from Python
 End of changes. 7 change blocks. 
23 lines changed or deleted 31 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)