Vips.Operation
Description: Reference for Vips.Operation

### Class

# VipsOperation

#### Description [src]

    abstract class Vips.Operation : Vips.Object
    {
      guint hash,
      gboolean found_hash,
      int pixels
    }

An abstract base class for all operations in libvips.

It builds on `VipsObject` to provide the introspection and command-line interface to libvips.

It also maintains a cache of recent operations. See below.

`vips_call()`, `vips_call_split()` and `vips_call_split_option_string()` are used by vips to implement the C API. They can execute any `VipsOperation`, passing in a set of required and optional arguments. Normally you would not use these functions directly: every operation has a tiny wrapper function which provides type-safety for the required arguments. For example, `vips_embed()` is defined as:

    int
    vips_embed(VipsImage *in, VipsImage **out,
        int x, int y, int width, int height, ...)
    {
        va_list ap;
        int result;

        va_start(ap, height);
        result = vips_call_split("embed", ap, in, out, x, y, width, height);
        va_end(ap);

        return result;
    }

Use `vips_call_argv()` to run any libvips operation from a command-line style argc/argv array. This is the thing used by the `vips` main program to implement the command-line interface.

## `VipsOperation` and reference counting

After calling a `VipsOperation` you are responsible for unreffing any output objects. For example, consider:

    VipsImage *im = ...;
    VipsImage *t1;

    if (vips_invert(im, &t1, NULL))
        error ..

This will invert `im` and return a new `VipsImage`, `t1`. As the caller of `vips_invert()`, you are responsible for `t1` and must unref it when you no longer need it. If `vips_invert()` fails, no `t1` is returned and you don’t need to do anything.

If you don’t need to use `im` for another operation, you can unref `im` immediately after the call. If `im` is needed to calculate `t1`, `vips_invert()` will add a ref to `im` and automatically drop it when `t1` is unreffed.

Consider running two operations, one after the other. You could write:

    VipsImage *im = ...;
    VipsImage *t1, *t2;

    if (vips_invert(im, &t1, NULL)) {
        g_object_unref(im);
        return -1;
    }
    g_object_unref(im);

    if (vips_flip(t1, &t2, VIPS_DIRECTION_HORIZONTAL, NULL)) {
        g_object_unref(t1);
        return -1;
    }
    g_object_unref(t1);

This is correct, but rather long-winded. libvips provides a handy thing to make a vector of auto-freeing object references. You can write this as:

    VipsObject *parent = ...;
    VipsImage *im = ...;
    VipsImage *t = (VipsImage **) vips_object_local_array(parent, 2);

    if (vips_invert(im, &t[0], NULL) ||
        vips_flip(t[0], &t[1], VIPS_DIRECTION_HORIZONTAL, NULL))
        return -1;

where `parent` is some enclosing object which will be unreffed when this task is complete. `vips_object_local_array()` makes an array of `VipsObject` (or `VipsImage`, in this case) where when `parent` is freed, all non-`NULL` `VipsObject` in the array are also unreffed.

## The `VipsOperation` cache

Because all `VipsObject` are immutable, they can be cached. The cache is very simple to use: instead of calling `vips_object_build()`, call `vips_cache_operation_build()`. This function calculates a hash from the operations’ input arguments and looks it up in table of all recent operations. If there’s a hit, the new operation is unreffed, the old operation reffed, and the old operation returned in place of the new one.

The cache size is controlled with `vips_cache_set_max()` and friends.

#### Ancestors

- VipsObject
- GObject

#### Descendants

- VipsForeign

#### Constructors

###### vips_operation_new

Return a new `VipsOperation` with the specified nickname. Useful for language bindings.

#### Functions

###### vips_operation_block_set

Set the block state on all operations in the libvips class hierarchy at `name` and below.

#### Instance methods

###### vips_operation_call_valist

No description available.

###### vips_operation_get_flags

Returns the set of flags for this operation.

###### vips_operation_invalidate

No description available.

##### Methods inherited from VipsObject (27)

Please see VipsObject for a full list of methods.

##### Methods inherited from GObject (43)

Please see GObject for a full list of methods.

#### Properties

##### Properties inherited from VipsObject (2)

###### Vips.Object:description

No description available.

###### Vips.Object:nickname

No description available.

#### Signals

###### Vips.Operation::invalidate

No description available.

##### Signals inherited from VipsObject (4)

###### VipsObject::close

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

###### VipsObject::postbuild

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

###### VipsObject::postclose

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

###### VipsObject::preclose

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

##### Signals inherited from GObject (1)

###### GObject::notify

The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al.

#### Class structure

    struct VipsOperationClass {
      VipsObjectClass parent_class;
      void (* usage) (
        _VipsOperationClass* cls,
        VipsBuf* buf
      );
      VipsOperationFlags (* get_flags) (
        VipsOperation* operation
      );
      VipsOperationFlags flags;
      void (* invalidate) (
        VipsOperation* operation
      );

    }

No description available.

###### Class members

`parent_class: VipsObjectClass`

  No description available.

`usage: void (* usage) ( _VipsOperationClass* cls, VipsBuf* buf )`

  No description available.

`get_flags: VipsOperationFlags (* get_flags) ( VipsOperation* operation )`

  No description available.

`flags: VipsOperationFlags`

  No description available.

`invalidate: void (* invalidate) ( VipsOperation* operation )`

  No description available.

#### Virtual methods

###### Vips.OperationClass.get_flags

Returns the set of flags for this operation.

###### Vips.OperationClass.invalidate

No description available.

#### Class methods

###### vips_operation_class_print_usage

Print a usage message for the operation to stdout.