more docs stuff
This commit is contained in:
John Cupitt
parent
7888526361
commit
2e3baa1bef
2
TODO
2
TODO
@ -1,3 +1,5 @@
|
||||
- bicubic needs a signed int lut path with rounding in the other direction
|
||||
for negatives
|
||||
|
||||
- vips_object_unref_outputs() needs docs ... bindings will need it
|
||||
|
||||
|
||||
@ -4,14 +4,14 @@
|
||||
]>
|
||||
<refentry id="using-from-c">
|
||||
<refmeta>
|
||||
<refentrytitle>Using VIPS from C</refentrytitle>
|
||||
<refentrytitle>VIPS from C</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
<refmiscinfo>VIPS Library</refmiscinfo>
|
||||
</refmeta>
|
||||
|
||||
<refnamediv>
|
||||
<refname>Using VIPS</refname>
|
||||
<refpurpose>How to use the VIPS library</refpurpose>
|
||||
<refpurpose>How to use the VIPS library from C</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 id="using-C">
|
||||
|
||||
@ -11,7 +11,7 @@
|
||||
|
||||
<refnamediv>
|
||||
<refname>Using VIPS</refname>
|
||||
<refpurpose>How to use the VIPS library</refpurpose>
|
||||
<refpurpose>How to use the VIPS library from the command-line</refpurpose>
|
||||
</refnamediv>
|
||||
|
||||
<refsect1 id="using-command-line">
|
||||
|
||||
@ -77,7 +77,85 @@
|
||||
* <emphasis>Command-line interface</emphasis> Any vips object can be run from
|
||||
* the command-line with the `vips` driver program.
|
||||
*
|
||||
* ## The #VipsObject lifecycle
|
||||
*
|
||||
* #VipsObject s have a strictly defined lifecycle, split broadly as construct
|
||||
* and then use. In detail, the stages are:
|
||||
*
|
||||
* 1. g_object_new(). The #VipsObject is created with g_object_new(). Objects
|
||||
* in this state are blank slates and need to have their various parameters
|
||||
* set.
|
||||
*
|
||||
* 2. g_object_set(). You loop over the #VipsArgument that the object has
|
||||
* defined with vips_argument_map(). Arguments have a set of flags attached to
|
||||
* them for required, optional, input, output, type, and so on. You must set
|
||||
* all required arguments.
|
||||
*
|
||||
* 3. vips_object_build(). Call this to construct the object and get it ready
|
||||
* for use. Building an object happens in four stages, see below.
|
||||
*
|
||||
* 4. g_object_get(). The object has now been built. You can read out any
|
||||
* computed values.
|
||||
*
|
||||
* 5. g_object_unref(). When you are done with an object, you can unref it.
|
||||
* See the section on reference counting for an explanation of the convention
|
||||
* that #VipsObject uses. When the last ref to an object is released, the
|
||||
* object is closed. Objects close in three stages, see below.
|
||||
*
|
||||
* The stages inside vips_object_build() are:
|
||||
*
|
||||
* 1. Chain up through the object's @build class methods. At each stage,
|
||||
* each object does any initial setup and checking, then chains up to its
|
||||
* superclass.
|
||||
*
|
||||
* 2. The innermost @build method in #VipsObject itself checks that all input
|
||||
* arguments have been set and then returns.
|
||||
*
|
||||
* 3. All object @build methods now finish executing, from innermost to
|
||||
* outermost. They know all input arguments have been checked and supplied, so
|
||||
* now they set all output arguments.
|
||||
*
|
||||
* 4. vips_object_build() finishes the process by checking that all output
|
||||
* objects have been set, and then triggering the #VipsObject::postbuild
|
||||
* signal. #VipsObject::postbuild only runs if the object has constructed
|
||||
* successfuly.
|
||||
*
|
||||
* And the stages inside close are:
|
||||
*
|
||||
* 1. #VipsObject::preclose. This is emitted at the start of
|
||||
* the #VipsObject dispose. The object is still functioning.
|
||||
*
|
||||
* 2. #VipsObject::close. This runs just after all #VipsArgument held by
|
||||
* the object have been released.
|
||||
*
|
||||
* 3. #VipsObject::postclose. This runs right at the end. The object
|
||||
* pointer is still valid, but nothing else is.
|
||||
*
|
||||
* ## The #VipsOperation cache
|
||||
*
|
||||
* Because all #VipsObject are immutable, they can be cached. The cache is
|
||||
* very simple to use: instead of calling vips_object_build(), instead call
|
||||
* vips_cache_operation_build(). This function calculates a hash from the
|
||||
* operations's input arguments and looks it up in table of all recent
|
||||
* operations. If there's a hit, the new operation is unreffed, the old
|
||||
* operation reffed, and the old operation returned in place of the new one.
|
||||
*
|
||||
* The cache size is controlled with vips_cache_set_max() and friends.
|
||||
*
|
||||
* ## The #VipsObject reference counting convention
|
||||
*
|
||||
* #VipsObject has a set of conventions to simplify reference counting.
|
||||
*
|
||||
* 1. All input %GObject have a ref added to them, owned by the object. When a
|
||||
* #VipsObject is unreffed, all of these refs to input objects are
|
||||
* automatically dropped.
|
||||
*
|
||||
* 2. All output %GObject hold a ref to the object. When a %GObject which is an
|
||||
* output of a #VipsObject is disposed, it must drop this reference.
|
||||
* #VipsObject which are outputs of other #VipsObject will do this
|
||||
* automatically.
|
||||
*
|
||||
* See #VipsOperation for an example of #VipsObject reference counting.
|
||||
*
|
||||
*/
|
||||
|
||||
@ -1504,6 +1582,13 @@ vips_object_class_init( VipsObjectClass *class )
|
||||
G_STRUCT_OFFSET( VipsObject, description ),
|
||||
"" );
|
||||
|
||||
/**
|
||||
* VipsObject::postbuild:
|
||||
* @object: the object that has been built
|
||||
*
|
||||
* The ::postbuild signal is emitted once just after successful object
|
||||
* construction. Return non-zero to cause object construction to fail.
|
||||
*/
|
||||
vips_object_signals[SIG_POSTBUILD] = g_signal_new( "postbuild",
|
||||
G_TYPE_FROM_CLASS( class ),
|
||||
G_SIGNAL_RUN_LAST,
|
||||
@ -1511,6 +1596,14 @@ vips_object_class_init( VipsObjectClass *class )
|
||||
NULL, NULL,
|
||||
vips_INT__VOID,
|
||||
G_TYPE_INT, 0 );
|
||||
|
||||
/**
|
||||
* VipsObject::preclose:
|
||||
* @object: the object that is to close
|
||||
*
|
||||
* The ::preclose signal is emitted once just before object close
|
||||
* starts. The oject is still alive.
|
||||
*/
|
||||
vips_object_signals[SIG_PRECLOSE] = g_signal_new( "preclose",
|
||||
G_TYPE_FROM_CLASS( class ),
|
||||
G_SIGNAL_RUN_LAST,
|
||||
@ -1518,6 +1611,14 @@ vips_object_class_init( VipsObjectClass *class )
|
||||
NULL, NULL,
|
||||
g_cclosure_marshal_VOID__VOID,
|
||||
G_TYPE_NONE, 0 );
|
||||
|
||||
/**
|
||||
* VipsObject::close:
|
||||
* @object: the object that is closing
|
||||
*
|
||||
* The ::close signal is emitted once during object close. The object
|
||||
* is dying and may not work.
|
||||
*/
|
||||
vips_object_signals[SIG_CLOSE] = g_signal_new( "close",
|
||||
G_TYPE_FROM_CLASS( class ),
|
||||
G_SIGNAL_RUN_LAST,
|
||||
@ -1525,6 +1626,14 @@ vips_object_class_init( VipsObjectClass *class )
|
||||
NULL, NULL,
|
||||
g_cclosure_marshal_VOID__VOID,
|
||||
G_TYPE_NONE, 0 );
|
||||
|
||||
/**
|
||||
* VipsObject::postclose:
|
||||
* @object: the object that has closed
|
||||
*
|
||||
* The ::postclose signal is emitted once after object close. The
|
||||
* object pointer is still valid, but nothing else.
|
||||
*/
|
||||
vips_object_signals[SIG_POSTCLOSE] = g_signal_new( "postclose",
|
||||
G_TYPE_FROM_CLASS( class ),
|
||||
G_SIGNAL_RUN_LAST,
|
||||
|
||||
@ -94,11 +94,69 @@
|
||||
* 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.
|
||||
* partially-built object. See
|
||||
* <link linkend="binding">binding</link> for an introduction to libvips
|
||||
* introspection.
|
||||
*
|
||||
* Use vips_call_argv() to run any vips operation from a command-line style
|
||||
* argc/argv array. This is the thing used by the vips main program to
|
||||
* implement the vips command-line interface.
|
||||
*
|
||||
* ## #VipsOperation and reference counting
|
||||
*
|
||||
* After calling a #VipsOperation you are responsible for unreffing any output
|
||||
* objects. For example, consider:
|
||||
*
|
||||
* |[
|
||||
* VipsImage *im = ...;
|
||||
* VipsImage *t1;
|
||||
*
|
||||
* if (vips_invert (im, &t1, NULL))
|
||||
* error ..
|
||||
* ]|
|
||||
*
|
||||
* This will invert @im and return it as a new #VipsImage, @t1. As the caller
|
||||
* of vips_invert(), you are responsible for @t1 and must unref it when you no
|
||||
* longer need it. If vips_invert() fails, no @t1 is returned and you don't
|
||||
* need to do anything.
|
||||
*
|
||||
* Consider running two operations, one after the other. You could write:
|
||||
*
|
||||
* |[
|
||||
* VipsImage *im = ...;
|
||||
* VipsImage *t1, *t2;
|
||||
*
|
||||
* if (vips_invert (im, &t1, NULL)) {
|
||||
* g_object_unref (im);
|
||||
* return -1;
|
||||
* }
|
||||
* g_object_unref (im);
|
||||
*
|
||||
* if (vips_flip (t1, &t2, VIPS_DIRECTION_HORIZONTAL, NULL)) {
|
||||
* g_object_unref (t1);
|
||||
* return -1;
|
||||
* }
|
||||
* g_object_unref (t1);
|
||||
* ]|
|
||||
*
|
||||
* This is correct, but rather long-winded. libvips provides a handy thing to
|
||||
* make a vector of auto-freeing object references. You can write this as:
|
||||
*
|
||||
* |[
|
||||
* VipsObject *parent = ...;
|
||||
* VipsImage *im = ...;
|
||||
* VipsImage *t = (VipsImage **) vips_object_local_array (parent, 2);
|
||||
*
|
||||
* if (vips_invert (im, &t[0], NULL) ||
|
||||
* vips_flip (t[0], &t[1], VIPS_DIRECTION_HORIZONTAL, NULL))
|
||||
* return -1;
|
||||
* ]|
|
||||
*
|
||||
* where @parent is some enclosing object which will be unreffed when this
|
||||
* task is complete. vips_object_local_array() makes an array of #VipsObject
|
||||
* (or #VipsImage, in this case) where when @parent is freed, all non-NULL
|
||||
* #VipsObject in the array are also unreffed.
|
||||
*
|
||||
*/
|
||||
|
||||
/**
|
||||
|
||||
Loading…
Reference in New Issue
Block a user