135 lines
3.9 KiB
TeX
135 lines
3.9 KiB
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}
|
|
|