--- name: "VipsObject" section: "3" platform: "linux" package: "libvips-dev" version: "7.20.7-1+b3" release: "Debian 6.0 (Squeeze)" platforms: ["linux"] url: "https://new.carta.tech/VipsObject" --- # VipsObject(3) VIPS base class ## 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 ## SYNOPSIS \#include \ /\* 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 .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.\ \ \*/\ 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. ## SEE ALSO [VipsFormat(3)](/VipsFormat/3.md), [VipsInterpolate(3)](/VipsInterpolate/3.md), vips\_type\_find(3). ## AUTHOR John Cupitt