SYNOPSIS

#include <vips/vips.h>

/* Flags we associate with each argument.

 */
typedef enum _VipsArgumentFlags {

  VIPS_ARGUMENT_NONE = 0,

  /* Must be set in the constructor.

   */

  VIPS_ARGUMENT_REQUIRED = 1,

  /* Can only be set in the constructor.

   */

  VIPS_ARGUMENT_CONSTRUCT = 2,

  /* Can only be set once.

   */

  VIPS_ARGUMENT_SET_ONCE = 4,

  /* Have input & output flags. Both set is an error; neither set 

   * is OK.

   */

  /* Is an input argument (one we depend on) ... if it's a gobject, we 

   * should ref it. In our _dispose(), we should unref it.

   */

  VIPS_ARGUMENT_INPUT = 8,

  /* Is an output argument (one that depends on us) ... if it's a

   * gobject, we should ref ourselves. We watch "destroy" on the

   * argument: if it goes, we unref ourselves. If we dispose, we

   * disconnect the signal.

   */

  VIPS_ARGUMENT_OUTPUT = 16
} 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 

   for an arithmetic operation

 */

#define VIPS_ARGUMENT_REQUIRED_INPUT

  (VIPS_ARGUMENT_INPUT | VIPS_ARGUMENT_REQUIRED | 
   VIPS_ARGUMENT_CONSTRUCT | VIPS_ARGUMENT_SET_ONCE)

#define VIPS_ARGUMENT_OPTIONAL_INPUT

  (VIPS_ARGUMENT_INPUT | 
   VIPS_ARGUMENT_CONSTRUCT | VIPS_ARGUMENT_SET_ONCE)

#define VIPS_ARGUMENT_REQUIRED_OUTPUT

  (VIPS_ARGUMENT_OUTPUT | VIPS_ARGUMENT_REQUIRED | 
   VIPS_ARGUMENT_SET_ONCE)

#define VIPS_ARGUMENT_OPTIONAL_OUTPUT

  (VIPS_ARGUMENT_OUTPUT | 
   VIPS_ARGUMENT_SET_ONCE)

/* Keep one of these for every argument.

 */
typedef struct _VipsArgument {

  GParamSpec *pspec;    /* pspec for this argument */

  /* More stuff, see below */
} VipsArgument;

typedef void *(*VipsArgumentMapFn)( VipsObject *, GParamSpec *,

  VipsArgumentClass *, VipsArgumentInstance *, void *a, void *b );
void *vips_argument_map( VipsObject *object,

  VipsArgumentMapFn fn, void *a, void *b );

struct _VipsObject {

  GObject parent_object;

};

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.

   */

  void (*print_class)( struct _VipsObjectClass *, VipsBuf * );

  /* Try to print something about the object, handy for debugging.

   */

  void (*print)( VipsObject *, VipsBuf * );

  /* 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;

};

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

int vips_object_build( VipsObject *object );
void vips_object_print_class( VipsObjectClass *klass );
void vips_object_print( VipsObject *object );

void vips_object_class_install_argument( VipsObjectClass *,

  GParamSpec *pspec, VipsArgumentFlags flags, guint offset );

typedef void *(*VipsObjectSetArguments)( VipsObject *,

  void *, void * );
VipsObject *vips_object_new( GType type,

  VipsObjectSetArguments set, void *a, void *b );

VipsObject *vips_object_new_from_string( const char *base,

  const char *str );
void vips_object_to_string( VipsObject *object, VipsBuf *buf );

DESCRIPTION

VipsObject is the base class for VIPS. It provides some common features, like class nicknames, and implements an extension to GObject for properties to let them be used more like function arguments.

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 VipsObject: VipsInterpolate and VipsFormat. Hopefully the next version will be more fleshed out.

VipsObject adds two properties: nickname and description. They are actually class properties, but are available as instance properties too for convenience.

nickname is the non-internationalised nickname of the class and is used to simplify lookup. For example, the VipsInterpolateBicubic class has the nickname "bicubic".

description is the internationalised short description of the class. For example, the VipsInterpolateBicubic class might have the description "bicubic interpolation (Catmull-Rom)".

Like the rest of VIPS, 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 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 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 g_object_new(3) you can continue to set arguments. After you have set all the ones you want to set, call vips_object_build(3) to check that required arguments have been set, no arguments have been set many times, and so on.

Once a VipsObject has been built, you can no longer set arguments, but you can read them.

Use 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.

vips_object_set_property(3) and vips_object_get_property(3) are used in subclasses of VipsObject to get and set object arguments. You don't need to implement your own get/set methods.

vips_object_new(3) is a convenience function which encapsulates the new/set/build sequence outlined above.

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.

vips_object_to_string(3) is the exact inverse: it prints the string that would construct an object.

RETURN VALUE

Unless otherwise noted, functions return 0 success and -1 on error.

AUTHOR

John Cupitt