VipsObject

VipsObject — the VIPS base object class

Stability Level

Stable, unless otherwise indicated

Functions

#define VIPS_UNREF()
#define VIPS_ARG_IMAGE()
#define VIPS_ARG_INTERPOLATE()
#define VIPS_ARG_BOOL()
#define VIPS_ARG_DOUBLE()
#define VIPS_ARG_BOXED()
#define VIPS_ARG_INT()
#define VIPS_ARG_UINT64()
#define VIPS_ARG_ENUM()
#define VIPS_ARG_FLAGS()
#define VIPS_ARG_STRING()
#define VIPS_ARG_POINTER()
VipsArgumentInstance * vips__argument_get_instance ()
VipsArgument * vips__argument_table_lookup ()
void vips__object_set_member ()
void * (*VipsArgumentMapFn) ()
void * vips_argument_map ()
void * (*VipsArgumentClassMapFn) ()
void * vips_argument_class_map ()
gboolean vips_argument_class_needsstring ()
int vips_object_get_argument ()
gboolean vips_object_argument_isset ()
VipsArgumentFlags vips_object_get_argument_flags ()
int vips_object_get_argument_priority ()
#define VIPS_ARGUMENT_FOR_ALL()
#define VIPS_ARGUMENT_COLLECT_SET()
#define VIPS_ARGUMENT_COLLECT_GET()
gboolean vips_value_is_null ()
void vips_object_set_property ()
void vips_object_get_property ()
void vips_object_preclose ()
int vips_object_build ()
void vips_object_summary_class ()
void vips_object_summary ()
void vips_object_dump ()
void vips_object_print_summary_class ()
void vips_object_print_summary ()
void vips_object_print_dump ()
void vips_object_print_name ()
gboolean vips_object_sanity ()
void vips_object_class_install_argument ()
int vips_object_set_argument_from_string ()
gboolean vips_object_argument_needsstring ()
int vips_object_get_argument_to_string ()
int vips_object_set_required ()
void * (*VipsObjectSetArguments) ()
VipsObject * vips_object_new ()
int vips_object_set_valist ()
int vips_object_set ()
int vips_object_set_from_string ()
VipsObject * vips_object_new_from_string ()
void vips_object_to_string ()
void * vips_object_map ()
void * (*VipsTypeMapFn) ()
void * (*VipsTypeMap2Fn) ()
void * (*VipsClassMapFn) ()
void * vips_type_map ()
void * vips_type_map_all ()
int vips_type_depth ()
GType vips_type_find ()
void * vips_class_map_all ()
VipsObjectClass * vips_class_find ()
VipsObject ** vips_object_local_array ()
void vips_object_local_cb ()
#define vips_object_local()
void vips_object_set_static ()
void vips_object_print_all ()
void vips_object_sanity_all ()
void vips_object_rewind ()
void vips_object_unref_outputs ()

Properties

gchar * description Read / Write
gchar * nickname Read / Write

Signals

void close Run Last
gint postbuild Run Last
void postclose Run Last
void preclose Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── VipsObject
        ├── VipsOperation
        ├── VipsImage
        ├── VipsInterpolate
        ├── VipsRegion
        ╰── VipsThreadState

Includes

#include <vips/vips.h>

Description

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.

Functions

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 *Param1,
                             VipsObject *Param2);

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


vips__argument_table_lookup ()

VipsArgument *
vips__argument_table_lookup (VipsArgumentTable *Param1,
                             GParamSpec *Param2);

vips__object_set_member ()

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

VipsArgumentMapFn ()

void *
(*VipsArgumentMapFn) (VipsObject *Param1,
                      GParamSpec *Param2,
                      VipsArgumentClass *Param3,
                      VipsArgumentInstance *Param4,
                      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.

Parameters

object

object whose args should be enumerated

 

fn

call this function for every argument

 

a

client data

 

b

client data

 

Returns

NULL if fn returns NULL for all arguments, otherwise the first non-NULL value from fn .


VipsArgumentClassMapFn ()

void *
(*VipsArgumentClassMapFn) (VipsObjectClass *Param1,
                           GParamSpec *Param2,
                           VipsArgumentClass *Param3,
                           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.

Parameters

object

the object to fetch the args from

 

name

arg to fetch

 

pspec

the pspec for this arg.

[transfer none]

argument_class

the argument_class for this arg.

[transfer none]

argument_instance

the argument_instance for this arg.

[transfer none]

Returns

0 on success, or -1 on error.


vips_object_argument_isset ()

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

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

Parameters

object

the object to fetch the args from

 

name

arg to fetch

 

Returns

TRUE if the argument has been assigned.


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.

Parameters

object

the object to fetch the args from

 

name

arg to fetch

 

Returns

The VipsArgmentFlags for this argument.


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.

Parameters

object

the object to fetch the args from

 

name

arg to fetch

 

Returns

The priority of this argument.


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);

vips_object_summary ()

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

vips_object_dump ()

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

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 *Param1,
                                    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 *Param1,
                           void *Param2,
                           void *Param3);

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.

Parameters

type

object to create

 

set

set arguments with this

 

a

client data

 

b

client data

 

Returns

the new object


vips_object_set_valist ()

int
vips_object_set_valist (VipsObject *object,
                        va_list ap);

See vips_object_set().

Parameters

object

object to set arguments on

 

ap

NULL-terminated list of argument/value pairs

 

Returns

0 on success, -1 on error


vips_object_set ()

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

Parameters

object

object to set arguments on

 

...

NULL-terminated list of argument/value pairs

 

Returns

0 on success, -1 on error


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

Parameters

object

object to set arguments on

 

string

arguments as a string

 

Returns

0 on success, -1 on error


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 an object into eg. "VipsInterpolateSnohalo1(blur=.333333)".

Parameters

object

object to stringify

 

buf

write string here

 

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.

Parameters

fn

function to call for all objects

 

a

client data

 

b

client data

 

Returns

NULL if fn returns NULL for all arguments, otherwise the first non-NULL value from fn .


VipsTypeMapFn ()

void *
(*VipsTypeMapFn) (GType Param1,
                  void *Param2);

VipsTypeMap2Fn ()

void *
(*VipsTypeMap2Fn) (GType Param1,
                   void *Param2,
                   void *Param3);

VipsClassMapFn ()

void *
(*VipsClassMapFn) (VipsObjectClass *Param1,
                   void *Param2);

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.

Parameters

base

base type

 

fn

call this function for every type

 

a

client data

 

b

client data

 

Returns

NULL if fn returns NULL for all arguments, otherwise the first non-NULL value from fn .


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.

Parameters

base

base type

 

fn

call this function for every type

 

a

client data

 

Returns

NULL if fn returns NULL for all arguments, otherwise the first non-NULL value from fn .


vips_type_depth ()

int
vips_type_depth (GType type);

vips_type_find ()

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

vips_class_map_all ()

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

Loop over all the subclasses of a base type. Non-abstract classes only.


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.

Parameters

basename

name of base class

 

nickname

search for a class with this nickname

 

Returns

the found class.


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:

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

Parameters

parent

objects unref when this object unrefs

 

n

array size

 

Returns

an array of NULL pointers of length n


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);

Types and Values

enum VipsArgumentFlags

VipsArgumentFlags is deprecated and should not be used in newly-written code.

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.

Members

VIPS_ARGUMENT_NONE

no flags

 

VIPS_ARGUMENT_REQUIRED

must be set in the constructor

 

VIPS_ARGUMENT_CONSTRUCT

can only be set in the constructor

 

VIPS_ARGUMENT_SET_ONCE

can only be set once

 

VIPS_ARGUMENT_SET_ALWAYS

don't do use-before-set checks

 

VIPS_ARGUMENT_INPUT

is an input argument (one we depend on)

 

VIPS_ARGUMENT_OUTPUT

is an output argument (depends on us)

 

VIPS_ARGUMENT_DEPRECATED

just there for back-compat, hide

 

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

Property Details

The “description” property

  “description”              gchar *

Class description.

Flags: Read / Write

Default value: ""


The “nickname” property

  “nickname”                 gchar *

Class nickname.

Flags: Read / Write

Default value: ""

Signal Details

The “close” signal

void
user_function (VipsObject *vipsobject,
               gpointer    user_data)

Flags: Run Last


The “postbuild” signal

gint
user_function (VipsObject *vipsobject,
               gpointer    user_data)

Flags: Run Last


The “postclose” signal

void
user_function (VipsObject *vipsobject,
               gpointer    user_data)

Flags: Run Last


The “preclose” signal

void
user_function (VipsObject *vipsobject,
               gpointer    user_data)

Flags: Run Last

See Also

operation