src/parsec/disk-image/parsec/parsec-benchmark/pkgs/apps/vips/src/doc/src/object.tex

\section{The VIPS base class: \texttt{VipsObject}}
\label{sec:object}

VIPS is in the process of moving to an object system based on \verb+GObject+.
You can read about the \verb+GObjec+ library at the GTK+ website:

\begin{verbatim}
http://www.gtk.org
\end{verbatim}

We've implemented two new subsystems (\verb+VipsFormat+ and
\verb+VipsInterpolate+) on top of \verb+VipsObject+ but not yet moved the core
VIPS types over. As a result, \verb+VipsObject+ is still developing and is
likely to change in the next release.

This section quickly summarises enough of the \verb+VipsObject+ system to let
you use the two derived APIs but that's all. Full documentation will come when
this system stabilises.

\subsection{Properties}

Like the rest of VIPS, \verb+VipsObject+ is a functional type. You can set
properties during object construction, but not after that point. You may read
properties at any time after construction, but not before.

To enforce these rules, VIPS extends the standard \verb+GObject+ property 
system and adds a new phase to object creation. An object has the following
stages in its life:

\subsubsection{Lookup}

\verb+vips_type_find()+ is a convenience function that looks up a type by its
nickname relative to a base class. For example:

\begin{verbatim}
GType type = 
  vips_type_find( "VipsInterpolate", "bilinear" );
\end{verbatim}

\noindent
finds a subclass of \verb+VipsInterpolate+ nicknamed `bilinear'. You can look
up types by their full name of course, but these can be rather unwieldy
(\verb+VipsInterpolateBilinear+ in this case, for example).

\subsubsection{Create}

Build an instance with \verb+g_object_new()+. For example:

\begin{verbatim}
VipsObject *object =
  g_object_new( type,
    "sharpness", 12.0,
    NULL );
\end{verbatim}

You can set any of the object's properties in the constructor. You can
continue to set, but not read, any other properties, for example:

\begin{verbatim}
g_object_set( object,
    "sharpness", 12.0,
    NULL );
\end{verbatim}

You can loop over an object's required and optional parameters with
\verb+vips_argument_map()+.

\subsubsection{Build}

Once all of the required any any of the optional object parameters have been
set, call \verb+vips_object_build()+:

\begin{verbatim}
int vips_object_build( VipsObject *object );
\end{verbatim}

This function checks that all the parameters have been set correctly and
starts the object working. It returns non-zero on error, setting
\verb+im_error_string()+.

\subsubsection{Use}

The object is now fully working. You can read results from it, or pass it on 
other objects. When you're finished with it, drop your reference to end its
life.

\begin{verbatim}
g_object_unref( object );
\end{verbatim}

\subsection{Convenience functions}

Two functions simplify building and printing objects.
\verb+vips_object_new_from_string()+ makes a new object which is a subclass of
a named base class.

\begin{verbatim}
VipsObject *
  vips_object_new_from_string( 
    const char *basename, const char *p );
\end{verbatim}

This is the function used by \verb+IM_INPUT_INTERPOLATE()+, for example, to
parse command-line arguments. The syntax is:

\begin{verbatim}
nickname [ ( required-arg1, 
  ...
  required-argn,
  optional-arg-name = value,
  ...
  optional-argm-name = value ) ]
\end{verbatim}

So values for all the required arguments, in the correct order, then name =
value for all the optional arguments you want to set. Parameters may be
enclosed in round or curly braces.

\verb+vips_object_to_string()+ is the exact opposite: it generates the 
construct string for any constructed
\verb+VipsObject+.

\verb+vips_object_new()+ wraps up the business of creating and checking an
object. It makes the object, uses the supplied function to attach any
arguments, then builds the object and returns NULL on failure or the new
object on success.

A switch to the \verb+vips+ command-line program is handy for listing subtypes
of \verb+VipsObject+. Try:

\begin{verbatim}
$ vips --list classes
\end{verbatim}