| .TH VIPS_OBJECT 3 "28 March 2009" |
| .SH NAME |
| VipsObject, |
| vips_object_build, vips_object_print_class, |
| vips_object_print, |
| vips_object_class_install_argument, |
| vips_argument_map, |
| vips_object_set_property, |
| vips_object_get_property, |
| vips_object_new, |
| vips_object_new_from_string, |
| vips_object_to_string |
| \- |
| VIPS base class |
| .SH SYNOPSIS |
| #include <vips/vips.h> |
| |
| /* Flags we associate with each argument. |
| .br |
| */ |
| .br |
| typedef enum _VipsArgumentFlags { |
| .br |
| VIPS_ARGUMENT_NONE = 0, |
| |
| /* Must be set in the constructor. |
| .br |
| */ |
| .br |
| VIPS_ARGUMENT_REQUIRED = 1, |
| |
| /* Can only be set in the constructor. |
| .br |
| */ |
| .br |
| VIPS_ARGUMENT_CONSTRUCT = 2, |
| |
| /* Can only be set once. |
| .br |
| */ |
| .br |
| VIPS_ARGUMENT_SET_ONCE = 4, |
| |
| /* Have input & output flags. Both set is an error; neither set |
| .br |
| * is OK. |
| .br |
| */ |
| |
| /* Is an input argument (one we depend on) ... if it's a gobject, we |
| .br |
| * should ref it. In our _dispose(), we should unref it. |
| .br |
| */ |
| .br |
| VIPS_ARGUMENT_INPUT = 8, |
| |
| /* Is an output argument (one that depends on us) ... if it's a |
| .br |
| * gobject, we should ref ourselves. We watch "destroy" on the |
| .br |
| * argument: if it goes, we unref ourselves. If we dispose, we |
| .br |
| * disconnect the signal. |
| .br |
| */ |
| .br |
| VIPS_ARGUMENT_OUTPUT = 16 |
| .br |
| } 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 |
| .br |
| for an arithmetic operation |
| |
| */ |
| |
| #define VIPS_ARGUMENT_REQUIRED_INPUT \ |
| .br |
| (VIPS_ARGUMENT_INPUT | VIPS_ARGUMENT_REQUIRED | \ |
| .br |
| VIPS_ARGUMENT_CONSTRUCT | VIPS_ARGUMENT_SET_ONCE) |
| |
| #define VIPS_ARGUMENT_OPTIONAL_INPUT \ |
| .br |
| (VIPS_ARGUMENT_INPUT | \ |
| .br |
| VIPS_ARGUMENT_CONSTRUCT | VIPS_ARGUMENT_SET_ONCE) |
| |
| #define VIPS_ARGUMENT_REQUIRED_OUTPUT \ |
| .br |
| (VIPS_ARGUMENT_OUTPUT | VIPS_ARGUMENT_REQUIRED | \ |
| .br |
| VIPS_ARGUMENT_SET_ONCE) |
| |
| #define VIPS_ARGUMENT_OPTIONAL_OUTPUT \ |
| .br |
| (VIPS_ARGUMENT_OUTPUT | \ |
| .br |
| VIPS_ARGUMENT_SET_ONCE) |
| |
| /* Keep one of these for every argument. |
| .br |
| */ |
| .br |
| typedef struct _VipsArgument { |
| .br |
| GParamSpec *pspec; /* pspec for this argument */ |
| |
| /* More stuff, see below */ |
| .br |
| } VipsArgument; |
| |
| typedef void *(*VipsArgumentMapFn)( VipsObject *, GParamSpec *, |
| .br |
| VipsArgumentClass *, VipsArgumentInstance *, void *a, void *b ); |
| .br |
| void *vips_argument_map( VipsObject *object, |
| .br |
| VipsArgumentMapFn fn, void *a, void *b ); |
| |
| struct _VipsObject { |
| .br |
| GObject parent_object; |
| |
| }; |
| |
| struct _VipsObjectClass { |
| .br |
| GObjectClass parent_class; |
| |
| /* Build the object ... all argument properties have been set, |
| .br |
| * now build the thing. |
| .br |
| */ |
| .br |
| int (*build)( VipsObject *object ); |
| |
| /* Try to print something about the class, handy for help displays. |
| .br |
| */ |
| .br |
| void (*print_class)( struct _VipsObjectClass *, VipsBuf * ); |
| |
| /* Try to print something about the object, handy for debugging. |
| .br |
| */ |
| .br |
| void (*print)( VipsObject *, VipsBuf * ); |
| |
| /* Class nickname, eg. "VipsInterpolateBicubic" has "bicubic" as a |
| .br |
| * nickname. Not internationalised. |
| .br |
| */ |
| .br |
| const char *nickname; |
| |
| /* Class description. Used for help messages, so internationalised. |
| .br |
| */ |
| .br |
| const char *description; |
| |
| }; |
| |
| void vips_object_set_property( GObject *gobject, |
| .br |
| guint property_id, const GValue *value, GParamSpec *pspec ); |
| .br |
| void vips_object_get_property( GObject *gobject, |
| .br |
| guint property_id, GValue *value, GParamSpec *pspec ); |
| |
| int vips_object_build( VipsObject *object ); |
| .br |
| void vips_object_print_class( VipsObjectClass *klass ); |
| .br |
| void vips_object_print( VipsObject *object ); |
| |
| void vips_object_class_install_argument( VipsObjectClass *, |
| .br |
| GParamSpec *pspec, VipsArgumentFlags flags, guint offset ); |
| |
| typedef void *(*VipsObjectSetArguments)( VipsObject *, |
| .br |
| void *, void * ); |
| .br |
| VipsObject *vips_object_new( GType type, |
| .br |
| VipsObjectSetArguments set, void *a, void *b ); |
| |
| VipsObject *vips_object_new_from_string( const char *base, |
| .br |
| const char *str ); |
| .br |
| void vips_object_to_string( VipsObject *object, VipsBuf *buf ); |
| |
| .SH DESCRIPTION |
| .B VipsObject |
| is the base class for VIPS. It provides some common features, like class |
| nicknames, and implements an extension to |
| .B GObject |
| for properties to let them be used more like function arguments. |
| |
| .B 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 |
| .B VipsObject: |
| .B VipsInterpolate |
| and |
| .B VipsFormat. |
| Hopefully the next version will be more fleshed out. |
| |
| .B VipsObject |
| adds two properties: |
| .B nickname |
| and |
| .B description. |
| They are actually class properties, but are available as instance properties |
| too for convenience. |
| |
| .B nickname |
| is the non-internationalised nickname of the class and is used to simplify |
| lookup. For example, the |
| .B VipsInterpolateBicubic |
| class has the nickname "bicubic". |
| |
| .B description |
| is the internationalised short description of the class. |
| For example, the |
| .B VipsInterpolateBicubic |
| class might have the description "bicubic interpolation (Catmull-Rom)". |
| |
| Like the rest of VIPS, |
| .B 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 |
| .B 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 |
| .B 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 |
| .B g_object_new(3) |
| you can continue to set arguments. After you have set all the ones you want to |
| set, call |
| .B vips_object_build(3) |
| to check that required arguments have been set, no arguments have been set |
| many times, and so on. |
| |
| Once a |
| .B VipsObject |
| has been built, you can no longer set arguments, but you can read them. |
| |
| Use |
| .B 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. |
| |
| .B vips_object_set_property(3) |
| and |
| .B vips_object_get_property(3) |
| are used in subclasses of |
| .B VipsObject |
| to get and set object arguments. You don't need to implement your own get/set |
| methods. |
| |
| .B vips_object_new(3) |
| is a convenience function which encapsulates the new/set/build sequence |
| outlined above. |
| |
| .B 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. |
| |
| .B vips_object_to_string(3) |
| is the exact inverse: it prints the string that would construct an object. |
| |
| .SH RETURN VALUE |
| Unless otherwise noted, functions return 0 success and -1 on error. |
| .SH SEE ALSO |
| VipsFormat(3), VipsInterpolate(3), |
| vips_type_find(3). |
| .SH AUTHOR |
| John Cupitt |