318 lines
7.4 KiB
Groff
318 lines
7.4 KiB
Groff
|
.TH VIPS_OBJECT 3 "28 March 2009"
|
||
|
|
.SH NAME
|
||
|
|
VipsObject,
|
||
|
|
vips_object_build, vips_object_print_class,
|
||
|
|
vips_object_print,
|
||
|
|
vips_object_class_install_argument,
|
||
|
|
vips_argument_map,
|
||
|
|
vips_object_set_property,
|
||
|
|
vips_object_get_property,
|
||
|
|
vips_object_new,
|
||
|
|
vips_object_new_from_string,
|
||
|
|
vips_object_to_string
|
||
|
|
\-
|
||
|
|
VIPS base class
|
||
|
|
.SH SYNOPSIS
|
||
|
|
#include <vips/vips.h>
|
||
|
|
|
||
|
|
/* Flags we associate with each argument.
|
||
|
|
.br
|
||
|
|
*/
|
||
|
|
.br
|
||
|
|
typedef enum _VipsArgumentFlags {
|
||
|
|
.br
|
||
|
|
VIPS_ARGUMENT_NONE = 0,
|
||
|
|
|
||
|
|
/* Must be set in the constructor.
|
||
|
|
.br
|
||
|
|
*/
|
||
|
|
.br
|
||
|
|
VIPS_ARGUMENT_REQUIRED = 1,
|
||
|
|
|
||
|
|
/* Can only be set in the constructor.
|
||
|
|
.br
|
||
|
|
*/
|
||
|
|
.br
|
||
|
|
VIPS_ARGUMENT_CONSTRUCT = 2,
|
||
|
|
|
||
|
|
/* Can only be set once.
|
||
|
|
.br
|
||
|
|
*/
|
||
|
|
.br
|
||
|
|
VIPS_ARGUMENT_SET_ONCE = 4,
|
||
|
|
|
||
|
|
/* Have input & output flags. Both set is an error; neither set
|
||
|
|
.br
|
||
|
|
* is OK.
|
||
|
|
.br
|
||
|
|
*/
|
||
|
|
|
||
|
|
/* Is an input argument (one we depend on) ... if it's a gobject, we
|
||
|
|
.br
|
||
|
|
* should ref it. In our _dispose(), we should unref it.
|
||
|
|
.br
|
||
|
|
*/
|
||
|
|
.br
|
||
|
|
VIPS_ARGUMENT_INPUT = 8,
|
||
|
|
|
||
|
|
/* Is an output argument (one that depends on us) ... if it's a
|
||
|
|
.br
|
||
|
|
* gobject, we should ref ourselves. We watch "destroy" on the
|
||
|
|
.br
|
||
|
|
* argument: if it goes, we unref ourselves. If we dispose, we
|
||
|
|
.br
|
||
|
|
* disconnect the signal.
|
||
|
|
.br
|
||
|
|
*/
|
||
|
|
.br
|
||
|
|
VIPS_ARGUMENT_OUTPUT = 16
|
||
|
|
.br
|
||
|
|
} VipsArgumentFlags;
|
||
|
|
|
||
|
|
/* Useful flag combinations. User-visible ones are:
|
||
|
|
|
||
|
|
VIPS_ARGUMENT_REQURED_INPUT Eg. the "left" argument for add
|
||
|
|
|
||
|
|
VIPS_ARGUMENT_OPTIONAL_INPUT Eg. the "caption" for an object
|
||
|
|
|
||
|
|
VIPS_ARGUMENT_REQURED_OUTPUT Eg. the "result" of an add operation
|
||
|
|
|
||
|
|
VIPS_ARGUMENT_OPTIONAL_OUTPUT Eg. the "width" of an image
|
||
|
|
|
||
|
|
Other combinations are used internally, eg. supplying the cast-table
|
||
|
|
.br
|
||
|
|
for an arithmetic operation
|
||
|
|
|
||
|
|
*/
|
||
|
|
|
||
|
|
#define VIPS_ARGUMENT_REQUIRED_INPUT \
|
||
|
|
.br
|
||
|
|
(VIPS_ARGUMENT_INPUT | VIPS_ARGUMENT_REQUIRED | \
|
||
|
|
.br
|
||
|
|
VIPS_ARGUMENT_CONSTRUCT | VIPS_ARGUMENT_SET_ONCE)
|
||
|
|
|
||
|
|
#define VIPS_ARGUMENT_OPTIONAL_INPUT \
|
||
|
|
.br
|
||
|
|
(VIPS_ARGUMENT_INPUT | \
|
||
|
|
.br
|
||
|
|
VIPS_ARGUMENT_CONSTRUCT | VIPS_ARGUMENT_SET_ONCE)
|
||
|
|
|
||
|
|
#define VIPS_ARGUMENT_REQUIRED_OUTPUT \
|
||
|
|
.br
|
||
|
|
(VIPS_ARGUMENT_OUTPUT | VIPS_ARGUMENT_REQUIRED | \
|
||
|
|
.br
|
||
|
|
VIPS_ARGUMENT_SET_ONCE)
|
||
|
|
|
||
|
|
#define VIPS_ARGUMENT_OPTIONAL_OUTPUT \
|
||
|
|
.br
|
||
|
|
(VIPS_ARGUMENT_OUTPUT | \
|
||
|
|
.br
|
||
|
|
VIPS_ARGUMENT_SET_ONCE)
|
||
|
|
|
||
|
|
/* Keep one of these for every argument.
|
||
|
|
.br
|
||
|
|
*/
|
||
|
|
.br
|
||
|
|
typedef struct _VipsArgument {
|
||
|
|
.br
|
||
|
|
GParamSpec *pspec; /* pspec for this argument */
|
||
|
|
|
||
|
|
/* More stuff, see below */
|
||
|
|
.br
|
||
|
|
} VipsArgument;
|
||
|
|
|
||
|
|
typedef void *(*VipsArgumentMapFn)( VipsObject *, GParamSpec *,
|
||
|
|
.br
|
||
|
|
VipsArgumentClass *, VipsArgumentInstance *, void *a, void *b );
|
||
|
|
.br
|
||
|
|
void *vips_argument_map( VipsObject *object,
|
||
|
|
.br
|
||
|
|
VipsArgumentMapFn fn, void *a, void *b );
|
||
|
|
|
||
|
|
struct _VipsObject {
|
||
|
|
.br
|
||
|
|
GObject parent_object;
|
||
|
|
|
||
|
|
};
|
||
|
|
|
||
|
|
struct _VipsObjectClass {
|
||
|
|
.br
|
||
|
|
GObjectClass parent_class;
|
||
|
|
|
||
|
|
/* Build the object ... all argument properties have been set,
|
||
|
|
.br
|
||
|
|
* now build the thing.
|
||
|
|
.br
|
||
|
|
*/
|
||
|
|
.br
|
||
|
|
int (*build)( VipsObject *object );
|
||
|
|
|
||
|
|
/* Try to print something about the class, handy for help displays.
|
||
|
|
.br
|
||
|
|
*/
|
||
|
|
.br
|
||
|
|
void (*print_class)( struct _VipsObjectClass *, VipsBuf * );
|
||
|
|
|
||
|
|
/* Try to print something about the object, handy for debugging.
|
||
|
|
.br
|
||
|
|
*/
|
||
|
|
.br
|
||
|
|
void (*print)( VipsObject *, VipsBuf * );
|
||
|
|
|
||
|
|
/* Class nickname, eg. "VipsInterpolateBicubic" has "bicubic" as a
|
||
|
|
.br
|
||
|
|
* nickname. Not internationalised.
|
||
|
|
.br
|
||
|
|
*/
|
||
|
|
.br
|
||
|
|
const char *nickname;
|
||
|
|
|
||
|
|
/* Class description. Used for help messages, so internationalised.
|
||
|
|
.br
|
||
|
|
*/
|
||
|
|
.br
|
||
|
|
const char *description;
|
||
|
|
|
||
|
|
};
|
||
|
|
|
||
|
|
void vips_object_set_property( GObject *gobject,
|
||
|
|
.br
|
||
|
|
guint property_id, const GValue *value, GParamSpec *pspec );
|
||
|
|
.br
|
||
|
|
void vips_object_get_property( GObject *gobject,
|
||
|
|
.br
|
||
|
|
guint property_id, GValue *value, GParamSpec *pspec );
|
||
|
|
|
||
|
|
int vips_object_build( VipsObject *object );
|
||
|
|
.br
|
||
|
|
void vips_object_print_class( VipsObjectClass *klass );
|
||
|
|
.br
|
||
|
|
void vips_object_print( VipsObject *object );
|
||
|
|
|
||
|
|
void vips_object_class_install_argument( VipsObjectClass *,
|
||
|
|
.br
|
||
|
|
GParamSpec *pspec, VipsArgumentFlags flags, guint offset );
|
||
|
|
|
||
|
|
typedef void *(*VipsObjectSetArguments)( VipsObject *,
|
||
|
|
.br
|
||
|
|
void *, void * );
|
||
|
|
.br
|
||
|
|
VipsObject *vips_object_new( GType type,
|
||
|
|
.br
|
||
|
|
VipsObjectSetArguments set, void *a, void *b );
|
||
|
|
|
||
|
|
VipsObject *vips_object_new_from_string( const char *base,
|
||
|
|
.br
|
||
|
|
const char *str );
|
||
|
|
.br
|
||
|
|
void vips_object_to_string( VipsObject *object, VipsBuf *buf );
|
||
|
|
|
||
|
|
.SH DESCRIPTION
|
||
|
|
.B VipsObject
|
||
|
|
is the base class for VIPS. It provides some common features, like class
|
||
|
|
nicknames, and implements an extension to
|
||
|
|
.B GObject
|
||
|
|
for properties to let them be used more like function arguments.
|
||
|
|
|
||
|
|
.B VipsObject
|
||
|
|
is still being developed, so this documentation only covers enough of the
|
||
|
|
interface to let you use the classes that have been built on top of
|
||
|
|
.B VipsObject:
|
||
|
|
.B VipsInterpolate
|
||
|
|
and
|
||
|
|
.B VipsFormat.
|
||
|
|
Hopefully the next version will be more fleshed out.
|
||
|
|
|
||
|
|
.B VipsObject
|
||
|
|
adds two properties:
|
||
|
|
.B nickname
|
||
|
|
and
|
||
|
|
.B description.
|
||
|
|
They are actually class properties, but are available as instance properties
|
||
|
|
too for convenience.
|
||
|
|
|
||
|
|
.B nickname
|
||
|
|
is the non-internationalised nickname of the class and is used to simplify
|
||
|
|
lookup. For example, the
|
||
|
|
.B VipsInterpolateBicubic
|
||
|
|
class has the nickname "bicubic".
|
||
|
|
|
||
|
|
.B description
|
||
|
|
is the internationalised short description of the class.
|
||
|
|
For example, the
|
||
|
|
.B VipsInterpolateBicubic
|
||
|
|
class might have the description "bicubic interpolation (Catmull-Rom)".
|
||
|
|
|
||
|
|
Like the rest of VIPS,
|
||
|
|
.B 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
|
||
|
|
.B GObject
|
||
|
|
property
|
||
|
|
system and adds a new phase to object creation.
|
||
|
|
|
||
|
|
In class_init, after creating a property, you make it into an argument by
|
||
|
|
adding a call to
|
||
|
|
.B vips_object_class_install_argument(3).
|
||
|
|
This takes a set of flags, used to tell VIPS what sort of argument this is,
|
||
|
|
and an offset for the data value in the class instance. For example:
|
||
|
|
|
||
|
|
pspec = g_param_spec_string( "description",
|
||
|
|
_( "Description" ),
|
||
|
|
_( "Class description" ),
|
||
|
|
"",
|
||
|
|
(GParamFlags) G_PARAM_READWRITE );
|
||
|
|
g_object_class_install_property( gobject_class,
|
||
|
|
PROP_DESCRIPTION, pspec );
|
||
|
|
vips_object_class_install_argument( object_class, pspec,
|
||
|
|
VIPS_ARGUMENT_SET_ONCE,
|
||
|
|
G_STRUCT_OFFSET( VipsObject, description ) );
|
||
|
|
|
||
|
|
After
|
||
|
|
.B g_object_new(3)
|
||
|
|
you can continue to set arguments. After you have set all the ones you want to
|
||
|
|
set, call
|
||
|
|
.B vips_object_build(3)
|
||
|
|
to check that required arguments have been set, no arguments have been set
|
||
|
|
many times, and so on.
|
||
|
|
|
||
|
|
Once a
|
||
|
|
.B VipsObject
|
||
|
|
has been built, you can no longer set arguments, but you can read them.
|
||
|
|
|
||
|
|
Use
|
||
|
|
.B vips_argument_map(3)
|
||
|
|
to iterate over the arguments for an object in the correct order. You can use
|
||
|
|
this to discover the arguments any class takes at runtime.
|
||
|
|
|
||
|
|
.B vips_object_set_property(3)
|
||
|
|
and
|
||
|
|
.B vips_object_get_property(3)
|
||
|
|
are used in subclasses of
|
||
|
|
.B VipsObject
|
||
|
|
to get and set object arguments. You don't need to implement your own get/set
|
||
|
|
methods.
|
||
|
|
|
||
|
|
.B vips_object_new(3)
|
||
|
|
is a convenience function which encapsulates the new/set/build sequence
|
||
|
|
outlined above.
|
||
|
|
|
||
|
|
.B vips_object_new_from_string(3)
|
||
|
|
is a convenience function which builds an object from a set of arguments
|
||
|
|
encoded as a string. It used used by the VIPS command-line program to generate
|
||
|
|
operation arguments.
|
||
|
|
|
||
|
|
.B vips_object_to_string(3)
|
||
|
|
is the exact inverse: it prints the string that would construct an object.
|
||
|
|
|
||
|
|
.SH RETURN VALUE
|
||
|
|
Unless otherwise noted, functions return 0 success and -1 on error.
|
||
|
|
.SH SEE ALSO
|
||
|
|
VipsFormat(3), VipsInterpolate(3),
|
||
|
|
vips_type_find(3).
|
||
|
|
.SH AUTHOR
|
||
|
|
John Cupitt
|