|  |  |  | VIPS Reference Manual |  | 
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Properties | Signals | ||||
#include <vips/vips.h> #define VIPS_UNREF (X) enum VipsArgumentFlags; #define VIPS_ARGUMENT_REQUIRED_INPUT #define VIPS_ARGUMENT_OPTIONAL_INPUT #define VIPS_ARGUMENT_REQUIRED_OUTPUT #define VIPS_ARGUMENT_OPTIONAL_OUTPUT #define VIPS_ARG_IMAGE (CLASS, NAME, PRIORITY, LONG, DESC, FLAGS, OFFSET) #define VIPS_ARG_INTERPOLATE (CLASS, NAME, PRIORITY, LONG, DESC, FLAGS, OFFSET) #define VIPS_ARG_BOOL (CLASS, NAME, PRIORITY, LONG, DESC, FLAGS, OFFSET, VALUE) #define VIPS_ARG_DOUBLE (CLASS, NAME, PRIORITY, LONG, DESC, FLAGS, OFFSET, MIN, MAX, VALUE) #define VIPS_ARG_BOXED (CLASS, NAME, PRIORITY, LONG, DESC, FLAGS, OFFSET, TYPE) #define VIPS_ARG_INT (CLASS, NAME, PRIORITY, LONG, DESC, FLAGS, OFFSET, MIN, MAX, VALUE) #define VIPS_ARG_UINT64 (CLASS, NAME, PRIORITY, LONG, DESC, FLAGS, OFFSET, MIN, MAX, VALUE) #define VIPS_ARG_ENUM (CLASS, NAME, PRIORITY, LONG, DESC, FLAGS, OFFSET, TYPE, VALUE) #define VIPS_ARG_FLAGS (CLASS, NAME, PRIORITY, LONG, DESC, FLAGS, OFFSET, TYPE, VALUE) #define VIPS_ARG_STRING (CLASS, NAME, PRIORITY, LONG, DESC, FLAGS, OFFSET, VALUE) #define VIPS_ARG_POINTER (CLASS, NAME, PRIORITY, LONG, DESC, FLAGS, OFFSET) VipsArgument; VipsArgumentClass; VipsArgumentInstance; typedef VipsArgumentTable; VipsArgumentInstance * vips__argument_get_instance (VipsArgumentClass *Param1,VipsObject *Param2); VipsArgument * vips__argument_table_lookup (VipsArgumentTable *Param1,GParamSpec *Param2); void vips__object_set_member (VipsObject *object,GParamSpec *pspec,GObject **member,GObject *argument); void * (*VipsArgumentMapFn) (VipsObject *Param1,GParamSpec *Param2,VipsArgumentClass *Param3,VipsArgumentInstance *Param4,void *a,void *b); void * vips_argument_map (VipsObject *object,VipsArgumentMapFn fn,void *a,void *b); void * (*VipsArgumentClassMapFn) (VipsObjectClass *Param1,GParamSpec *Param2,VipsArgumentClass *Param3,void *a,void *b); void * vips_argument_class_map (VipsObjectClass *object_class,VipsArgumentClassMapFn fn,void *a,void *b); int vips_object_get_argument (VipsObject *object,const char *name,GParamSpec **pspec,VipsArgumentClass **argument_class,VipsArgumentInstance **argument_instance); gboolean vips_object_argument_isset (VipsObject *object,const char *name); VipsArgumentFlags vips_object_get_argument_flags (VipsObject *object,const char *name); int vips_object_get_argument_priority (VipsObject *object,const char *name); #define VIPS_ARGUMENT_FOR_ALL (OBJECT, PSPEC, ARG_CLASS, ARG_INSTANCE) #define VIPS_ARGUMENT_COLLECT_SET (PSPEC, ARG_CLASS, AP) #define VIPS_ARGUMENT_COLLECT_GET (PSPEC, ARG_CLASS, AP) #define VIPS_ARGUMENT_COLLECT_END struct VipsObject; struct VipsObjectClass; gboolean vips_value_is_null (GParamSpec *psoec,const GValue *value); void vips_object_set_property (GObject *gobject,guint property_id,const GValue *value,GParamSpec *pspec); void vips_object_get_property (GObject *gobject,guint property_id,GValue *value,GParamSpec *pspec); void vips_object_preclose (VipsObject *object); int vips_object_build (VipsObject *object); void vips_object_summary_class (VipsObjectClass *klass,VipsBuf *buf); void vips_object_summary (VipsObject *object,VipsBuf *buf); void vips_object_dump (VipsObject *object,VipsBuf *buf); void vips_object_print_summary_class (VipsObjectClass *klass); void vips_object_print_summary (VipsObject *object); void vips_object_print_dump (VipsObject *object); void vips_object_print_name (VipsObject *object); gboolean vips_object_sanity (VipsObject *object); void vips_object_class_install_argument (VipsObjectClass *Param1,GParamSpec *pspec,VipsArgumentFlags flags,int priority,guint offset); int vips_object_set_argument_from_string (VipsObject *object,const char *name,const char *value); gboolean vips_object_argument_needsstring (VipsObject *object,const char *name); int vips_object_get_argument_to_string (VipsObject *object,const char *name,const char *arg); int vips_object_set_required (VipsObject *object,const char *value); void * (*VipsObjectSetArguments) (VipsObject *Param1,void *Param2,void *Param3); VipsObject * vips_object_new (GType type,VipsObjectSetArguments set,void *a,void *b); int vips_object_set_valist (VipsObject *object,va_list ap); int vips_object_set (VipsObject *object,...); VipsObject * vips_object_new_from_string (VipsObjectClass *object_class,const char *p); void vips_object_to_string (VipsObject *object,VipsBuf *buf); void * vips_object_map (VipsSListMap2Fn fn,void *a,void *b); void * (*VipsTypeMapFn) (GType Param1,void *Param2); void * (*VipsTypeMap2Fn) (GType Param1,void *Param2,void *Param3); void * (*VipsClassMapFn) (VipsObjectClass *Param1,void *Param2); void * vips_type_map (GType base,VipsTypeMap2Fn fn,void *a,void *b); void * vips_type_map_all (GType base,VipsTypeMapFn fn,void *a); int vips_type_depth (GType type); GType vips_type_find (const char *basename,const char *nickname); void * vips_class_map_all (GType base,VipsClassMapFn fn,void *a); VipsObjectClass * vips_class_find (const char *basename,const char *nickname); VipsObject ** vips_object_local_array (VipsObject *parent,int n); void vips_object_local_cb (VipsObject *vobject,GObject *gobject); #define vips_object_local (V, G) void vips_object_set_static (VipsObject *object,gboolean static_object); void vips_object_print_all (void); void vips_object_sanity_all (void); void vips_object_rewind (VipsObject *object); void vips_object_unref_outputs (VipsObject *object);
  GObject
   +----VipsObject
         +----VipsOperation
         +----VipsImage
         +----VipsInterpolate
         +----VipsRegion
         +----VipsThreadState
The VipsObject class and associated types and macros.
VipsObject is the base class for all objects in libvips. It has the following major features:
Functional class creation Vips objects have a very regular lifecycle: initialise, build, use, destroy. They behave rather like function calls and are free of side-effects.
Run-time introspection Vips objects can be fully introspected at run-time. There is not need for a separate source-code analysis.
Command-line interface Vips objects have an automatic command-line line interface with a set of virtual methods.
typedef enum {
	VIPS_ARGUMENT_NONE = 0,
	VIPS_ARGUMENT_REQUIRED = 1,
	VIPS_ARGUMENT_CONSTRUCT = 2,
	VIPS_ARGUMENT_SET_ONCE = 4,
	VIPS_ARGUMENT_SET_ALWAYS = 8,
	VIPS_ARGUMENT_INPUT = 16,
	VIPS_ARGUMENT_OUTPUT = 32,
	VIPS_ARGUMENT_DEPRECATED = 64
} VipsArgumentFlags;
Flags we associate with each object argument.
Have separate input & output flags. Both set is an error; neither set is OK.
Input gobjects are automatically reffed, output gobjects automatically ref us. We also automatically watch for "destroy" and unlink.
VIPS_ARGUMENT_SET_ALWAYS is handy for arguments which are set from C. For
example, VipsImage::width is a property that gives access to the Xsize
member of struct _VipsImage. We default its 'assigned' to TRUE
since the field is always set directly by C.
VIPS_ARGUMENT_DEPRECATED arguments are not shown in help text, are not
looked for if required, are not checked for "have-been-set". You can
deprecate a required argument, but you must obviously add a new required
argument if you do.
| no flags | |
| must be set in the constructor | |
| can only be set in the constructor | |
| can only be set once | |
| don't do use-before-set checks | |
| is an input argument (one we depend on) | |
| is an output argument (depends on us) | |
| just there for back-compat, hide | 
#define VIPS_ARG_INTERPOLATE( CLASS, NAME, PRIORITY, LONG, DESC, FLAGS, OFFSET )
#define             VIPS_ARG_DOUBLE( CLASS, NAME, PRIORITY, LONG, DESC, \
            	FLAGS, OFFSET, MIN, MAX, VALUE )
#define             VIPS_ARG_INT( CLASS, NAME, PRIORITY, LONG, DESC, \
            	FLAGS, OFFSET, MIN, MAX, VALUE )
#define             VIPS_ARG_UINT64( CLASS, NAME, PRIORITY, LONG, DESC, \
            	FLAGS, OFFSET, MIN, MAX, VALUE )
#define             VIPS_ARG_ENUM( CLASS, NAME, PRIORITY, LONG, DESC, \
            	FLAGS, OFFSET, TYPE, VALUE )
#define             VIPS_ARG_FLAGS( CLASS, NAME, PRIORITY, LONG, DESC, \
            	FLAGS, OFFSET, TYPE, VALUE )
#define             VIPS_ARG_STRING( CLASS, NAME, PRIORITY, LONG, DESC, FLAGS, OFFSET, \
            	VALUE )
typedef struct {
	GParamSpec *pspec; /* pspec for this argument */
	/* More stuff, see below */
} VipsArgument;
typedef struct {
	VipsArgument parent;
	/* The class of the object we are an arg for.
	 */
	VipsObjectClass *object_class;
	VipsArgumentFlags flags;
	int priority;		/* Order args by this */
	guint offset;		/* G_STRUCT_OFFSET of member in object */
} VipsArgumentClass;
typedef struct {
	VipsArgument parent;
	/* The class we are part of.
	 */
	VipsArgumentClass *argument_class;
	/* The object we are attached to.
	 */
	VipsObject *object;
	/* Has been set.
	 */
	gboolean assigned;
	/* If this is an output argument, keep the id of our "close" handler
	 * here.
	 */
	gulong close_id;	
} VipsArgumentInstance;
VipsArgumentInstance * vips__argument_get_instance (VipsArgumentClass *Param1,VipsObject *Param2);
Convenience ... given the VipsArgumentClass, get the VipsArgumentInstance.
VipsArgument * vips__argument_table_lookup (VipsArgumentTable *Param1,GParamSpec *Param2);
void vips__object_set_member (VipsObject *object,GParamSpec *pspec,GObject **member,GObject *argument);
void * (*VipsArgumentMapFn) (VipsObject *Param1,GParamSpec *Param2,VipsArgumentClass *Param3,VipsArgumentInstance *Param4,void *a,void *b);
void * vips_argument_map (VipsObject *object,VipsArgumentMapFn fn,void *a,void *b);
Loop over the vips_arguments to an object. Stop when fn returns non-NULL
and return that value.
| 
 | object whose args should be enumerated | 
| 
 | call this function for every argument | 
| 
 | client data | 
| 
 | client data | 
| Returns : | NULLiffnreturnsNULLfor all arguments, otherwise the first
non-NULLvalue fromfn. | 
void * (*VipsArgumentClassMapFn) (VipsObjectClass *Param1,GParamSpec *Param2,VipsArgumentClass *Param3,void *a,void *b);
void * vips_argument_class_map (VipsObjectClass *object_class,VipsArgumentClassMapFn fn,void *a,void *b);
And loop over a class. Same as ^^, but with no VipsArgumentInstance.
int vips_object_get_argument (VipsObject *object,const char *name,GParamSpec **pspec,VipsArgumentClass **argument_class,VipsArgumentInstance **argument_instance);
Look up the three things you need to work with a vips argument.
| 
 | the object to fetch the args from | 
| 
 | arg to fetch | 
| 
 | the pspec for this arg. [transfer none] | 
| 
 | the argument_class for this arg. [transfer none] | 
| 
 | the argument_instance for this arg. [transfer none] | 
| Returns : | 0 on success, or -1 on error. | 
gboolean vips_object_argument_isset (VipsObject *object,const char *name);
Convenience: has an argument been assigned. Useful for bindings.
| 
 | the object to fetch the args from | 
| 
 | arg to fetch | 
| Returns : | TRUEif the argument has been assigned. | 
VipsArgumentFlags vips_object_get_argument_flags (VipsObject *object,const char *name);
Convenience: get the flags for an argument. Useful for bindings.
| 
 | the object to fetch the args from | 
| 
 | arg to fetch | 
| Returns : | The VipsArgmentFlags for this argument. | 
int vips_object_get_argument_priority (VipsObject *object,const char *name);
Convenience: get the priority for an argument. Useful for bindings.
| 
 | the object to fetch the args from | 
| 
 | arg to fetch | 
| Returns : | The priority of this argument. | 
struct VipsObjectClass {
	GObjectClass parent_class;
	/* Build the object ... all argument properties have been set,
	 * now build the thing.
	 */
	int (*build)( VipsObject *object );
	/* Try to print something about the class, handy for help displays.
	 * Keep to one line.
	 */
	void (*summary_class)( struct _VipsObjectClass *, VipsBuf * );
	/* Try to print a one-line summary for the object, the user can see
	 * this output via things like "header fred.tif", --vips-cache-trace,
	 * etc. 
	 */
	void (*summary)( VipsObject *, VipsBuf * );
	/* Try to print everything about the object, handy for debugging.
	 */
	void (*dump)( VipsObject *, VipsBuf * );
	/* Sanity-check the object. Print messages and stuff. 
	 * Handy for debugging.
	 */
	void (*sanity)( VipsObject *, VipsBuf * );
	/* Rewind. Save and restore any stuff that needs to survive a
	 * dispose().
	 */
	void (*rewind)( VipsObject * );
	/* Just before close, everything is still alive.
	 */
	void (*preclose)( VipsObject * );
	/* Close, time to free stuff.
	 */
	void (*close)( VipsObject * );
	/* Post-close, everything is dead, except the VipsObject pointer.
	 * Useful for eg. deleting the file associated with a temp image.
	 */
	void (*postclose)( VipsObject * );
	/* The CLI interface. Implement these four to get CLI input and output
	 * for your object.
	 */
	/* Given a command-line arg (eg. a filename), make an instance of the
	 * object. Just do the g_object_new(), don't call _build().
	 *
	 * Don't call this directly, see vips_object_new_from_string().
	 */
	VipsObject *(*new_from_string)( const char *string );
	/* The inverse of ^^. Given an object, output what ->new_from_string()
	 * would have been given to make that object. 
	 */
	void (*to_string)( VipsObject *, VipsBuf * ); 
	/* Does this output arg need an arg from the command line? Image
	 * output, for example, needs a filename to write to.
	 */
	gboolean output_needs_arg;
	/* Write the object to the string. Return 0 for success, or -1 on
	 * error, setting vips_error(). string is NULL if output_needs_arg()
	 * was FALSE.
	 */
	int (*output_to_arg)( VipsObject *object, const char *string );
	/* Class nickname, eg. "VipsInterpolateBicubic" has "bicubic" as a
	 * nickname. Not internationalised. 
	 */
	const char *nickname;
	/* Class description. Used for help messages, so internationalised.
	 */
	const char *description;
	/* Hash from pspec to VipsArgumentClass.
	 *
	 * This records the VipsArgumentClass for every pspec used in 
	 * VipsObject and any subclass (ie. everywhere), so it's huge. Don't
	 * loop over this hash! Fine for lookups though.
	 */
	VipsArgumentTable *argument_table;
	/* A sorted (by priority) list of the VipsArgumentClass for this class 
	 * and any superclasses. This is small and specific to this class.
	 *
	 * Use the stored GType to work out when to restart the list for a
	 * subclass.
	 */
	GSList *argument_table_traverse;
	GType argument_table_traverse_gtype;
};
void vips_object_set_property (GObject *gobject,guint property_id,const GValue *value,GParamSpec *pspec);
void vips_object_get_property (GObject *gobject,guint property_id,GValue *value,GParamSpec *pspec);
void vips_object_class_install_argument (VipsObjectClass *Param1,GParamSpec *pspec,VipsArgumentFlags flags,int priority,guint offset);
int vips_object_set_argument_from_string (VipsObject *object,const char *name,const char *value);
gboolean vips_object_argument_needsstring (VipsObject *object,const char *name);
int vips_object_get_argument_to_string (VipsObject *object,const char *name,const char *arg);
void * (*VipsObjectSetArguments) (VipsObject *Param1,void *Param2,void *Param3);
VipsObject * vips_object_new (GType type,VipsObjectSetArguments set,void *a,void *b);
g_object_new() the object, set any arguments with set, call
vips_object_build() and return the complete object.
| 
 | object to create | 
| 
 | set arguments with this | 
| 
 | client data | 
| 
 | client data | 
| Returns : | the new object | 
int vips_object_set_valist (VipsObject *object,va_list ap);
See vips_object_set().
| 
 | object to set arguments on | 
| 
 | NULL-terminated list of argument/value pairs | 
| Returns : | 0 on success, -1 on error | 
int vips_object_set (VipsObject *object,...);
Set a list of vips object arguments. For example:
vips_object_set (operation, "input", in, "output", &out, NULL);
Input arguments are given in-line, output arguments are given as pointers to where the output value should be written.
See also: vips_object_set_valist().
| 
 | object to set arguments on | 
| 
 | NULL-terminated list of argument/value pairs | 
| Returns : | 0 on success, -1 on error | 
VipsObject * vips_object_new_from_string (VipsObjectClass *object_class,const char *p);
void vips_object_to_string (VipsObject *object,VipsBuf *buf);
The inverse of vips_object_new_from_string(): turn an object into eg.
"VipsInterpolateSnohalo1(blur=.333333)".
| 
 | object to stringify | 
| 
 | write string here | 
void * vips_object_map (VipsSListMap2Fn fn,void *a,void *b);
Call a function for all alive objects.
Stop when fn returns non-NULL and return that value.
| 
 | function to call for all objects | 
| 
 | client data | 
| 
 | client data | 
| Returns : | NULLiffnreturnsNULLfor all arguments, otherwise the first
non-NULLvalue fromfn. | 
void * vips_type_map (GType base,VipsTypeMap2Fn fn,void *a,void *b);
Map over a type's children. Stop when fn returns non-NULL
and return that value.
| 
 | base type | 
| 
 | call this function for every type | 
| 
 | client data | 
| 
 | client data | 
| Returns : | NULLiffnreturnsNULLfor all arguments, otherwise the first
non-NULLvalue fromfn. | 
void * vips_type_map_all (GType base,VipsTypeMapFn fn,void *a);
Map over a type's children, direct and indirect. Stop when fn returns 
non-NULL and return that value.
| 
 | base type | 
| 
 | call this function for every type | 
| 
 | client data | 
| Returns : | NULLiffnreturnsNULLfor all arguments, otherwise the first
non-NULLvalue fromfn. | 
void * vips_class_map_all (GType base,VipsClassMapFn fn,void *a);
Loop over all the subclasses of a base type. Non-abstract classes only.
VipsObjectClass * vips_class_find (const char *basename,const char *nickname);
Search below basename, return the first class whose name or nickname matches.
| 
 | name of base class | 
| 
 | search for a class with this nickname | 
| Returns : | the found class. | 
VipsObject ** vips_object_local_array (VipsObject *parent,int n);
Make an array of NULL VipsObject pointers. When parent closes, every
non-NULL pointer in the array will be unreffed and the array will be
freed. Handy for creating a set of temporary images for a function.
The array is NULL-terminated, ie. contains an extra NULL element at the end.
Example:
VipsObject **t; t = vips_object_local_array( a, 5 ); if( vips_add( a, b, &t[0], NULL ) || vips_invert( t[0], &t[1], NULL ) || vips_add( t[1], t[0], &t[2], NULL ) || vips_costra( t[2], out, NULL ) ) return( -1 );
See also: vips_object_local().
| 
 | objects unref when this object unrefs | 
| 
 | array size | 
| Returns : | an array of NULL pointers of length n | 
"close" signalvoid                user_function                      (VipsObject *vipsobject,
                                                        gpointer    user_data)       : Run Last
| 
 | the object which received the signal. | 
| 
 | user data set when the signal handler was connected. | 
"postclose" signalvoid                user_function                      (VipsObject *vipsobject,
                                                        gpointer    user_data)       : Run Last
| 
 | the object which received the signal. | 
| 
 | user data set when the signal handler was connected. | 
"preclose" signalvoid                user_function                      (VipsObject *vipsobject,
                                                        gpointer    user_data)       : Run Last
| 
 | the object which received the signal. | 
| 
 | user data set when the signal handler was connected. |