TheVipsObject lifecycle

VipsObject s have a strictly defined lifecycle, split broadly as constructand then use. In detail, the stages are:

The stages insidevips_object_build() are:

VipsOperation has a cache of recent operation objects, see that class foran explanation ofvips_cache_operation_build().

Finally the stages inside close are:

VipsArgument

libvips has a simple mechanism for automating at least some aspects ofGObject properties. You add a set of macros to your_class_init() whichdescribe the arguments, and set the get and set functions to the vips ones.

Seeextending for a complete example.

TheVipsObject reference counting convention

VipsObject has a set of conventions to simplify reference counting.

SeeVipsOperation for an example ofVipsObject reference counting.

VIPS_UNREF()

#define             VIPS_UNREF(X)

VIPS_ARG_IMAGE()

#define             VIPS_ARG_IMAGE(CLASS, NAME, PRIORITY, LONG, DESC, FLAGS, OFFSET)

VIPS_ARG_INTERPOLATE()

#define             VIPS_ARG_INTERPOLATE(CLASS, NAME, PRIORITY, LONG, DESC, FLAGS, OFFSET)

VIPS_ARG_BOOL()

#define             VIPS_ARG_BOOL(CLASS, NAME, PRIORITY, LONG, DESC, \            FLAGS, OFFSET, VALUE)

VIPS_ARG_DOUBLE()

#define             VIPS_ARG_DOUBLE(CLASS, NAME, PRIORITY, LONG, DESC, \            FLAGS, OFFSET, MIN, MAX, VALUE)

VIPS_ARG_BOXED()

#define             VIPS_ARG_BOXED(CLASS, NAME, PRIORITY, LONG, DESC, \            FLAGS, OFFSET, TYPE)

VIPS_ARG_INT()

#define             VIPS_ARG_INT(CLASS, NAME, PRIORITY, LONG, DESC, \            FLAGS, OFFSET, MIN, MAX, VALUE)

VIPS_ARG_UINT64()

#define             VIPS_ARG_UINT64(CLASS, NAME, PRIORITY, LONG, DESC, \            FLAGS, OFFSET, MIN, MAX, VALUE)

VIPS_ARG_ENUM()

#define             VIPS_ARG_ENUM(CLASS, NAME, PRIORITY, LONG, DESC, \            FLAGS, OFFSET, TYPE, VALUE)

VIPS_ARG_FLAGS()

#define             VIPS_ARG_FLAGS(CLASS, NAME, PRIORITY, LONG, DESC, \            FLAGS, OFFSET, TYPE, VALUE)

VIPS_ARG_STRING()

#define             VIPS_ARG_STRING(CLASS, NAME, PRIORITY, LONG, DESC, FLAGS, OFFSET, \            VALUE)

VIPS_ARG_POINTER()

#define             VIPS_ARG_POINTER(CLASS, NAME, PRIORITY, LONG, DESC, FLAGS, OFFSET)

vips_argument_get_id ()

intvips_argument_get_id (void);

Allocate a new property id. Seeg_object_class_install_property().

[skip]

vips__object_set_member ()

voidvips__object_set_member (VipsObject *object,GParamSpec *pspec,GObject **member,GObject *argument);

VipsArgumentMapFn ()

void *(*VipsArgumentMapFn) (VipsObject *object,GParamSpec *pspec,VipsArgumentClass *argument_class,VipsArgumentInstance *argument_instance,void *a,void *b);

vips_argument_map ()

void *vips_argument_map (VipsObject *object,VipsArgumentMapFn fn,void *a,void *b);

Loop over the vips_arguments to an object. Stop whenfn returns non-NULLand return that value.

[skip]

vips_object_get_args ()

intvips_object_get_args (VipsObject *object,constchar ***names,int **flags,int *n_args);

Get allGParamSpec names andVipsArgumentFlags for an object.

This is handy for language bindings. From C, it's usually more convenient tousevips_argument_map().

[skip]

VipsArgumentClassMapFn ()

void *(*VipsArgumentClassMapFn) (VipsObjectClass *object_class,GParamSpec *pspec,VipsArgumentClass *argument_class,void *a,void *b);

vips_argument_class_map ()

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.

[skip]

vips_argument_class_needsstring ()

gbooleanvips_argument_class_needsstring (VipsArgumentClass *argument_class);

vips_object_get_argument ()

intvips_object_get_argument (VipsObject *object,constchar *name,GParamSpec **pspec,VipsArgumentClass **argument_class,VipsArgumentInstance **argument_instance);

Look up the three things you need to work with a vips argument.

[skip]

vips_object_argument_isset ()

gbooleanvips_object_argument_isset (VipsObject *object,constchar *name);

Convenience: has an argument been assigned. Useful for bindings.

vips_object_get_argument_flags ()

VipsArgumentFlagsvips_object_get_argument_flags (VipsObject *object,constchar *name);

Convenience: get the flags for an argument. Useful for bindings.

vips_object_get_argument_priority ()

intvips_object_get_argument_priority (VipsObject *object,constchar *name);

Convenience: get the priority for an argument. Useful for bindings.

VIPS_ARGUMENT_FOR_ALL()

#define             VIPS_ARGUMENT_FOR_ALL(OBJECT, PSPEC, ARG_CLASS, ARG_INSTANCE)

VIPS_ARGUMENT_COLLECT_SET()

#define             VIPS_ARGUMENT_COLLECT_SET(PSPEC, ARG_CLASS, AP)

VIPS_ARGUMENT_COLLECT_GET()

#define             VIPS_ARGUMENT_COLLECT_GET(PSPEC, ARG_CLASS, AP)

vips_value_is_null ()

gbooleanvips_value_is_null (GParamSpec *psoec,constGValue *value);

vips_object_set_property ()

voidvips_object_set_property (GObject *gobject,guint property_id,constGValue *value,GParamSpec *pspec);

vips_object_get_property ()

voidvips_object_get_property (GObject *gobject,guint property_id,GValue *value,GParamSpec *pspec);

vips_object_preclose ()

voidvips_object_preclose (VipsObject *object);

vips_object_build ()

intvips_object_build (VipsObject *object);

vips_object_summary_class ()

voidvips_object_summary_class (VipsObjectClass *klass,VipsBuf *buf);

Generate a human-readable summary for a class.

[skip]

vips_object_summary ()

voidvips_object_summary (VipsObject *object,VipsBuf *buf);

Generate a human-readable summary for an object.

[skip]

vips_object_dump ()

voidvips_object_dump (VipsObject *object,VipsBuf *buf);

Dump everything that vips knows about an object to a string.

[skip]

vips_object_print_summary_class ()

voidvips_object_print_summary_class (VipsObjectClass *klass);

vips_object_print_summary ()

voidvips_object_print_summary (VipsObject *object);

vips_object_print_dump ()

voidvips_object_print_dump (VipsObject *object);

vips_object_print_name ()

voidvips_object_print_name (VipsObject *object);

vips_object_sanity ()

gbooleanvips_object_sanity (VipsObject *object);

vips_object_class_install_argument ()

voidvips_object_class_install_argument (VipsObjectClass *cls,GParamSpec *pspec,VipsArgumentFlags flags,int priority,guint offset);

vips_object_set_argument_from_string ()

intvips_object_set_argument_from_string (VipsObject *object,constchar *name,constchar *value);

vips_object_argument_needsstring ()

gbooleanvips_object_argument_needsstring (VipsObject *object,constchar *name);

vips_object_get_argument_to_string ()

intvips_object_get_argument_to_string (VipsObject *object,constchar *name,constchar *arg);

vips_object_set_required ()

intvips_object_set_required (VipsObject *object,constchar *value);

VipsObjectSetArguments ()

void *(*VipsObjectSetArguments) (VipsObject *object,void *a,void *b);

vips_object_new ()

VipsObject *vips_object_new (GType type,VipsObjectSetArguments set,void *a,void *b);

g_object_new() the object, set any arguments withset, callvips_object_build() and return the complete object.

[skip]

vips_object_set_valist ()

intvips_object_set_valist (VipsObject *object,va_list ap);

Seevips_object_set().

vips_object_set ()

intvips_object_set (VipsObject *object,...);

Set a list of vips object arguments. For example:

1234

vips_object_set(operation,"input",in,"output",&out,NULL);

Input arguments are given in-line, output arguments are given as pointersto where the output value should be written.

See also:vips_object_set_valist(),vips_object_set_from_string().

vips_object_set_from_string ()

intvips_object_set_from_string (VipsObject *object,constchar *string);

Set object arguments from a string. The string can be something like"a=12", or "a = 12, b = 13", or "fred". The string can optionally beenclosed in brackets.

You'd typically use this between creating the object and building it.

See also:vips_object_set(),vips_object_build(),vips_cache_operation_buildp().

vips_object_new_from_string ()

VipsObject *vips_object_new_from_string (VipsObjectClass *object_class,constchar *p);

vips_object_to_string ()

voidvips_object_to_string (VipsObject *object,VipsBuf *buf);

The inverse ofvips_object_new_from_string(): turnobject into eg."VipsInterpolateSnohalo1(blur=.333333)".

vips_object_map ()

void *vips_object_map (VipsSListMap2Fn fn,void *a,void *b);

Call a function for all alive objects.Stop whenfn returns non-NULL and return that value.

[skip]

VipsTypeMapFn ()

void *(*VipsTypeMapFn) (GType type,void *a);

VipsTypeMap2Fn ()

void *(*VipsTypeMap2Fn) (GType type,void *a,void *b);

VipsClassMapFn ()

void *(*VipsClassMapFn) (VipsObjectClass *cls,void *a);

vips_type_map ()

void *vips_type_map (GType base,VipsTypeMap2Fn fn,void *a,void *b);

Map over a type's children. Stop whenfn returns non-NULLand return that value.

[skip]

vips_type_map_all ()

void *vips_type_map_all (GType base,VipsTypeMapFn fn,void *a);

Map over a type's children, direct and indirect. Stop whenfn returnsnon-NULL and return that value.

[skip]

vips_type_depth ()

intvips_type_depth (GType type);

vips_type_find ()

GTypevips_type_find (constchar *basename,constchar *nickname);

Search belowbasename, return theGType of the class whose name ornickname matches, or 0 for not found.Ifbasename is NULL, the whole ofVipsObject is searched.

This function uses a cache, so it should be quick.

See also:vips_class_find()

vips_nickname_find ()

constchar *vips_nickname_find (GType type);

Return the VIPS nickname for aGType. Handy for language bindings.

vips_class_map_all ()

void *vips_class_map_all (GType type,VipsClassMapFn fn,void *a);

Loop over all the subclasses oftype. Non-abstract classes only.Stop whenfn returnsnon-NULL and return that value.

[skip]

vips_class_find ()

constVipsObjectClass *vips_class_find (constchar *basename,constchar *nickname);

Search belowbasename, return the first class whose name ornicknamematches.

See also:vips_type_find()

vips_object_local_array ()

VipsObject **vips_object_local_array (VipsObject *parent,int n);

Make an array of NULL VipsObject pointers. Whenparent closes, everynon-NULL pointer in the array will be unreffed and the array will befreed. Handy for creating a set of temporary images for a function.

The array is NULL-terminated, ie. contains an extra NULL element at theend.

Example:

12345678

VipsObject**t;t=vips_object_local_array(parent,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().

[skip]

vips_object_local_cb ()

voidvips_object_local_cb (VipsObject *vobject,GObject *gobject);

vips_object_local()

#define             vips_object_local(V, G)

vips_object_set_static ()

voidvips_object_set_static (VipsObject *object,gboolean static_object);

vips_object_print_all ()

voidvips_object_print_all (void);

vips_object_sanity_all ()

voidvips_object_sanity_all (void);

vips_object_rewind ()

voidvips_object_rewind (VipsObject *object);

vips_object_unref_outputs ()

voidvips_object_unref_outputs (VipsObject *object);

Unref all assigned output objects. Useful for language bindings.

After an object is built, all output args are owned by the caller. Ifsomething goes wrong before then, we have to unref the outputs that havebeen made so far. This function can also be useful for callers whenthey've finished processing outputs themselves.

See also:vips_cache_operation_build().

vips_object_get_description ()

constchar *vips_object_get_description (VipsObject *object);

Fetch the object description. Useful for language bindings.

object.description is only available after_build(), which can be toolate. This function fetches from the instance, if possible, but falls backto the class description if we are too early.

enum 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 refus. We also automatically watch for "destroy" and unlink.

VIPS_ARGUMENT_SET_ALWAYS is handy for arguments which are set from C. Forexample, VipsImage::width is a property that gives access to the Xsizemember of struct _VipsImage. We default its 'assigned' to TRUEsince the field is always set directly by C.

VIPS_ARGUMENT_DEPRECATED arguments are not shown in help text, are notlooked for if required, are not checked for "have-been-set". You candeprecate a required argument, but you must obviously add a new requiredargument if you do.

Input args withVIPS_ARGUMENT_MODIFY will be modified by the operation.This is used for things like the in-place drawing operations.

VIPS_ARGUMENT_NON_HASHABLE stops the argument being used in hash andequality tests. It's useful for arguments likerevalidate whichcontrol the behaviour of the operator cache.

VIPS_ARGUMENT_REQUIRED_INPUT

#define             VIPS_ARGUMENT_REQUIRED_INPUT

VIPS_ARGUMENT_OPTIONAL_INPUT

#define             VIPS_ARGUMENT_OPTIONAL_INPUT

VIPS_ARGUMENT_REQUIRED_OUTPUT

#define             VIPS_ARGUMENT_REQUIRED_OUTPUT

VIPS_ARGUMENT_OPTIONAL_OUTPUT

#define             VIPS_ARGUMENT_OPTIONAL_OUTPUT

VipsArgument

typedef struct {GParamSpec *pspec; /* pspec for this argument *//* More stuff, see below */} VipsArgument;

VipsArgumentClass

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;

VipsArgumentInstance

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;/* We need to listen for "invalidate" on input images and send our own * "invalidate" out. If we go, we need to disconnect. */gulong invalidate_id;} VipsArgumentInstance;

VipsArgumentTable

typedef GHashTable VipsArgumentTable;

VIPS_ARGUMENT_FOR_ALL_END

#define             VIPS_ARGUMENT_FOR_ALL_END

VIPS_ARGUMENT_COLLECT_END

#define             VIPS_ARGUMENT_COLLECT_END

The“description” property

  “description”char *

Class description.

Owner: VipsObject

Flags: Read / Write

Default value: ""

The“nickname” property

  “nickname”char *

Class nickname.

Owner: VipsObject

Flags: Read / Write

Default value: ""

The“close” signal

voiduser_function (VipsObject *object,gpointer    user_data)

The ::close signal is emitted once during object close. The objectis dying and may not work.

Flags: Run Last

The“postbuild” signal

intuser_function (VipsObject *object,gpointer    user_data)

The ::postbuild signal is emitted once just after successful objectconstruction. Return non-zero to cause object construction to fail.

Flags: Run Last

The“postclose” signal

voiduser_function (VipsObject *object,gpointer    user_data)

The ::postclose signal is emitted once after object close. Theobject pointer is still valid, but nothing else.

Flags: Run Last

The“preclose” signal

voiduser_function (VipsObject *object,gpointer    user_data)

The ::preclose signal is emitted once just before object closestarts. The object is still alive.

Flags: Run Last