sergiotarxz/libvips
sergiotarxz/libvips
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
John Cupitt 2019-12-06 16:58:47 +00:00
parent d10c870a32
commit 317feec6a4
1 changed files with 15 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
doc/binding.xml
View File

@ -16,7 +16,7 @@
<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. 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> </para>
<refsect3 id="dont-bind-the-top-level-c-api"> <section xml:id="dont-bind-the-top-level-c-api">
<title>Don’t bind the top-level C API</title> <title>Don’t bind the top-level C API</title>
<para> <para>
The libvips C API (vips_add() and so on) is very inconvenient and dangerous to use from other languages due to its heavy use of varargs. The libvips C API (vips_add() and so on) is very inconvenient and dangerous to use from other languages due to its heavy use of varargs.
@ -79,7 +79,7 @@ main( int argc, char **argv )
/* Call the operation. This will look up the operation+args in the vips /* Call the operation. This will look up the operation+args in the vips
* operation cache and either return a previous operation, or build * operation cache and either return a previous operation, or build
* this one. In either case, we have a new ref we mst release. * this one. In either case, we have a new ref we must release.
*/ */
if( !(new_op = vips_cache_operation_build( op )) ) { if( !(new_op = vips_cache_operation_build( op )) ) {
g_object_unref( op ); g_object_unref( op );
@ -112,13 +112,13 @@ main( int argc, char **argv )
} }
</programlisting> </programlisting>
<para> <para>
libvips has a couple of extra things to let you examine the arguments and types of an operator at runtime. 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. 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.
</para> </para>
<para> <para>
Use vips_operation_get_flags() to get general information about an operator. Use vips_operation_get_flags() to get general information about an operator.
</para> </para>
</refsect3> </section>
<refsect3 id="compiled-language-which-can-call-c"> <section xml:id="compiled-language-which-can-call-c">
<title>Compiled language which can call C</title> <title>Compiled language which can call C</title>
<para> <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. 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.
@ -144,23 +144,23 @@ VImage VImage::invert( VOption *options )
<para> <para>
The <literal>VImage</literal> class also adds automatic reference counting, constant expansion, operator overloads, and various other useful features. The <literal>VImage</literal> class also adds automatic reference counting, constant expansion, operator overloads, and various other useful features.
</para> </para>
</refsect3> </section>
<refsect3 id="dynamic-language-with-ffi"> <section xml:id="dynamic-language-with-ffi">
<title>Dynamic language with FFI</title> <title>Dynamic language with FFI</title>
<para> <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. 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++, but use FFI to call into libvips and run operations.
</para> </para>
<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 code and just expose everything they find in the libvips class hierarchy. 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 code and just expose everything they find in the libvips class hierarchy.
</para> </para>
</refsect3> </section>
<refsect3 id="dynamic-langauge-without-ffi"> <section xml:id="dynamic-langauge-without-ffi">
<title>Dynamic langauge without FFI</title> <title>Dynamic langauge without FFI</title>
<para> <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. 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.
</para> </para>
</refsect3> </section>
<refsect3 id="gobject-introspection"> <section xml:id="gobject-introspection">
<title>gobject-introspection</title> <title>gobject-introspection</title>
<para> <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 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: 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:
@ -177,8 +177,8 @@ from gi.repository import Vips
<para> <para>
If you have a choice, I would recommend simply using FFI. If you have a choice, I would recommend simply using FFI.
</para> </para>
</refsect3> </section>
<refsect3 id="documentation"> <section xml:id="documentation">
<title>Documentation</title> <title>Documentation</title>
<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: 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:
@ -202,7 +202,7 @@ $ yelp-build html .
<para> <para>
To make HTML docs. This is an easy way to see what you can call in the library. To make HTML docs. This is an easy way to see what you can call in the library.
</para> </para>
</refsect3> </section>
</refentry> </refentry>