The VipsObject lifecycle

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

The stages inside vips_object_build() are:

VipsOperation has a cache of recent operation objects, see that class for an explanation of vips_cache_operation_build().

Finally the stages inside close are:

VipsArgument

libvips has a simple mechanism for automating at least some aspects of GObject properties. You add a set of macros to your _class_init() which describe the arguments, and set the get and set functions to the vips ones.

See extending for a complete example.

The VipsObject reference counting convention

VipsObject has a set of conventions to simplify reference counting.

See VipsOperation for an example of VipsObject 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_instance ()

VipsArgumentInstance *
vips__argument_get_instance (VipsArgumentClass *argument_class,
                             VipsObject *object);

Convenience ... given the VipsArgumentClass, get the VipsArgumentInstance.

vips__argument_table_lookup ()

VipsArgument *
vips__argument_table_lookup (VipsArgumentTable *argument_class,
                             GParamSpec *pspec);

vips__object_set_member ()

void
vips__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 when fn returns non-NULL and return that value.

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.

vips_argument_class_needsstring ()

gboolean
vips_argument_class_needsstring (VipsArgumentClass *argument_class);

vips_object_get_argument ()

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.

vips_object_argument_isset ()

gboolean
vips_object_argument_isset (VipsObject *object,
                            const char *name);

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

vips_object_get_argument_flags ()

VipsArgumentFlags
vips_object_get_argument_flags (VipsObject *object,
                                const char *name);

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

vips_object_get_argument_priority ()

int
vips_object_get_argument_priority (VipsObject *object,
                                   const char *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 ()

gboolean
vips_value_is_null (GParamSpec *psoec,
                    const GValue *value);

vips_object_set_property ()

void
vips_object_set_property (GObject *gobject,
                          guint property_id,
                          const GValue *value,
                          GParamSpec *pspec);

vips_object_get_property ()

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

vips_object_preclose ()

void
vips_object_preclose (VipsObject *object);

vips_object_build ()

int
vips_object_build (VipsObject *object);

vips_object_summary_class ()

void
vips_object_summary_class (VipsObjectClass *klass,
                           VipsBuf *buf);

Generate a human-readable summary for a class.

vips_object_summary ()

void
vips_object_summary (VipsObject *object,
                     VipsBuf *buf);

Generate a human-readable summary for an object.

vips_object_dump ()

void
vips_object_dump (VipsObject *object,
                  VipsBuf *buf);

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

vips_object_print_summary_class ()

void
vips_object_print_summary_class (VipsObjectClass *klass);

vips_object_print_summary ()

void
vips_object_print_summary (VipsObject *object);

vips_object_print_dump ()

void
vips_object_print_dump (VipsObject *object);

vips_object_print_name ()

void
vips_object_print_name (VipsObject *object);

vips_object_sanity ()

gboolean
vips_object_sanity (VipsObject *object);

vips_object_class_install_argument ()

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

vips_object_set_argument_from_string ()

int
vips_object_set_argument_from_string (VipsObject *object,
                                      const char *name,
                                      const char *value);

vips_object_argument_needsstring ()

gboolean
vips_object_argument_needsstring (VipsObject *object,
                                  const char *name);

vips_object_get_argument_to_string ()

int
vips_object_get_argument_to_string (VipsObject *object,
                                    const char *name,
                                    const char *arg);

vips_object_set_required ()

int
vips_object_set_required (VipsObject *object,
                          const char *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 with set , call vips_object_build() and return the complete object.

vips_object_set_valist ()

int
vips_object_set_valist (VipsObject *object,
                        va_list ap);

See vips_object_set().

vips_object_set ()

int
vips_object_set (VipsObject *object,
                 ...);

Set a list of vips object arguments. For example:

1
2
3
4

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(), vips_object_set_from_string().

vips_object_set_from_string ()

int
vips_object_set_from_string (VipsObject *object,
                             const char *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 be enclosed 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,
                             const char *p);

vips_object_to_string ()

void
vips_object_to_string (VipsObject *object,
                       VipsBuf *buf);

The inverse of vips_object_new_from_string(): turn object 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 when fn returns non-NULL and return that value.

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 when fn returns non-NULL and return that value.

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 when fn returns non-NULL and return that value.

vips_type_depth ()

int
vips_type_depth (GType type);

vips_type_find ()

GType
vips_type_find (const char *basename,
                const char *nickname);

vips_nickname_find ()

const char *
vips_nickname_find (GType type);

Return the VIPS nickanme for a GType. Handy for language bindings.

vips_class_map_all ()

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

Loop over all the subclasses of type . Non-abstract classes only. Stop when fn returns non-NULL and return that value.

vips_class_find ()

VipsObjectClass *
vips_class_find (const char *basename,
                 const char *nickname);

Search below basename, return the first class whose name or nickname matches.

vips_object_local_array ()

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:

1
2
3
4
5
6
7
8
9

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().

vips_object_local_cb ()

void
vips_object_local_cb (VipsObject *vobject,
                      GObject *gobject);

vips_object_local()

#define             vips_object_local( V, G )

vips_object_set_static ()

void
vips_object_set_static (VipsObject *object,
                        gboolean static_object);

vips_object_print_all ()

void
vips_object_print_all (void);

vips_object_sanity_all ()

void
vips_object_sanity_all (void);

vips_object_rewind ()

void
vips_object_rewind (VipsObject *object);

vips_object_unref_outputs ()

void
vips_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. If something goes wrong before then, we have to unref the outputs that have been made so far. This function can also be useful for callers when they've finished processing outputs themselves.

See also: vips_cache_operation_build().

vips_object_get_description ()

const char *
vips_object_get_description (VipsObject *object);

Fetch the object description. Useful for language bindings.

object.description is only avaliable after _build(), which can be too late. This function fetches from the instance, if possible, but falls back to 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 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.

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

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_COLLECT_END

#define             VIPS_ARGUMENT_COLLECT_END

The “description” property

  “description”              gchar *

Class description.

Flags: Read / Write

Default value: ""

The “nickname” property

  “nickname”                 gchar *

Class nickname.

Flags: Read / Write

Default value: ""

The “close” signal

void
user_function (VipsObject *object,
               gpointer    user_data)

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

Flags: Run Last

The “postbuild” signal

gint
user_function (VipsObject *object,
               gpointer    user_data)

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

Flags: Run Last

The “postclose” signal

void
user_function (VipsObject *object,
               gpointer    user_data)

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

Flags: Run Last

The “preclose” signal

void
user_function (VipsObject *object,
               gpointer    user_data)

The ::preclose signal is emitted once just before object close starts. The oject is still alive.

Flags: Run Last