Vips.Object
Description: Reference for Vips.Object

### Class

# VipsObject

#### Description [src]

    abstract class Vips.Object : GObject.Object
    {
      gboolean constructed,
      gboolean static_object,
      VipsArgumentTable* argument_table,
      char* nickname,
      char* description,
      gboolean preclose,
      gboolean close,
      gboolean postclose,
      size_t local_memory
    }

An abstract base class for all objects in libvips.

It has the following major features:

- Functional class creation: libvips 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: libvips objects can be fully introspected at run-time. There is no need for separate source-code analysis.

- Command-line interface: Any vips object can be run from the command-line with the `vips` driver program.

## The `VipsObject` lifecycle

`VipsObject`‘s have a strictly defined lifecycle, split broadly as construct and then use. In detail, the stages are:

1. `g_object_new()`. The `VipsObject` is created with `g_object_new()`. Objects in this state are blank slates and need to have their various parameters set.

2. `g_object_set()`. You loop over the `VipsArgument` that the object has defined with `vips_argument_map()`. Arguments have a set of flags attached to them for required, optional, input, output, type, and so on. You must set all required arguments.

3. `vips_object_build()`. Call this to construct the object and get it ready for use. Building an object happens in four stages, see below.

4. `g_object_get()`. The object has now been built. You can read out any computed values.

5. `g_object_unref()`. When you are done with an object, you can unref it. See the section on reference counting for an explanation of the convention that `VipsObject` uses. When the last ref to an object is released, the object is closed. Objects close in three stages, see below.

The stages inside `vips_object_build()` are:

1. Chain up through the object’s `build` class methods. At each stage, each class does any initial setup and checking, then chains up to its superclass.

2. The innermost `build` method inside `VipsObject` itself checks that all input arguments have been set and then returns.

3. All object `build` methods now finish executing, from innermost to outermost. They know all input arguments have been checked and supplied, so now they set all output arguments.

4. `vips_object_build()` finishes the process by checking that all output objects have been set, and then triggering the `VipsObject::postbuild` signal. `VipsObject::postbuild` only runs if the object has constructed successfully.

`VipsOperation` has a cache of recent operation objects, see that class for an explanation of `vips_cache_operation_build()`.

Finally, the stages inside close are:

1. `VipsObject::preclose`. This is emitted at the start of the `VipsObject` dispose. The object is still functioning.

2. `VipsObject::close`. This runs just after all `VipsArgument` held by the object have been released.

3. `VipsObject::postclose`. This runs right at the end. The object pointer is still valid, but nothing else is.

## The `VipsObject` reference counting convention

`VipsObject` has a set of conventions to simplify reference counting.

1. All input `GObject` have a ref added to them, owned by the object. When a `VipsObject` is unreffed, all of these refs to input objects are automatically dropped.

2. All output `GObject` hold a ref to the object. When a `GObject` which is an output of a `VipsObject` is disposed, it must drop this reference. `VipsObject` which are outputs of other `VipsObject`‘s will do this automatically.

See `VipsOperation` for an example of `VipsObject` reference counting.

#### Hierarchy

#### Ancestors

- GObject

#### Descendants

- VipsConnection
- VipsImage
- VipsInterpolate
- VipsOperation
- VipsRegion
- VipsSbuf
- VipsThreadState

#### Constructors

###### vips_object_new

`g_object_new()` the object, set any arguments with `set`, call `vips_object_build()` and return the complete object.

###### vips_object_new_from_string

No description available.

#### Functions

###### vips_object_get_property

No description available.

###### vips_object_map

Call a function for all alive objects. Stop when `fn` returns non-`NULL` and return that value.

###### vips_object_print_all

No description available.

###### vips_object_print_summary_class

No description available.

###### vips_object_sanity_all

No description available.

###### vips_object_set_property

No description available.

###### vips_object_summary_class

Generate a human-readable summary for a class.

#### Instance methods

###### vips_object_argument_isset

###### vips_object_argument_needsstring

No description available.

###### vips_object_build

No description available.

###### vips_object_dump

Dump everything that vips knows about an object to a string.

###### vips_object_get_args

Get all `GParamSpec` names and `VipsArgumentFlags` for an object.

###### vips_object_get_argument

Look up the three things you need to work with a vips argument.

###### vips_object_get_argument_flags

###### vips_object_get_argument_priority

###### vips_object_get_argument_to_string

No description available.

###### vips_object_get_description

Fetch the object description. Useful for language bindings.

###### vips_object_local_array

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.

###### vips_object_local_cb

No description available.

###### vips_object_preclose

No description available.

###### vips_object_print_dump

No description available.

###### vips_object_print_name

No description available.

###### vips_object_print_summary

No description available.

###### vips_object_rewind

No description available.

###### vips_object_sanity

No description available.

###### vips_object_set

Set a list of vips object arguments. For example:.

###### vips_object_set_argument_from_string

No description available.

###### vips_object_set_from_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.

###### vips_object_set_required

No description available.

###### vips_object_set_static

No description available.

###### vips_object_set_valist

See `vips_object_set()`.

###### vips_object_summary

Generate a human-readable summary for an object.

###### vips_object_to_string

The inverse of `vips_object_new_from_string()`: turn `object` into eg. `"bicubic"`.

###### vips_object_unref_outputs

Unref all assigned output objects. Useful for language bindings.

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

Please see GObject for a full list of methods.

#### Properties

###### Vips.Object:description

No description available.

###### Vips.Object:nickname

No description available.

#### Signals

###### Vips.Object::close

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

###### Vips.Object::postbuild

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

###### Vips.Object::postclose

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

###### Vips.Object::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 VipsObjectClass {
      GObjectClass parent_class;
      int (* build) (
        VipsObject* object
      );
      int (* postbuild) (
        VipsObject* object,
        void* data
      );
      void (* summary_class) (
        _VipsObjectClass* cls,
        VipsBuf* buf
      );
      void (* summary) (
        VipsObject* object,
        VipsBuf* buf
      );
      void (* dump) (
        VipsObject* object,
        VipsBuf* buf
      );
      void (* sanity) (
        VipsObject* object,
        VipsBuf* buf
      );
      void (* rewind) (
        VipsObject* object
      );
      void (* preclose) (
        VipsObject* object
      );
      void (* close) (
        VipsObject* object
      );
      void (* postclose) (
        VipsObject* object
      );
      VipsObject* (* new_from_string) (
        const char* string
      );
      void (* to_string) (
        VipsObject* object,
        VipsBuf* buf
      );
      gboolean output_needs_arg;
      int (* output_to_arg) (
        VipsObject* object,
        const char* string
      );
      const char* nickname;
      const char* description;
      VipsArgumentTable* argument_table;
      gpointer argument_table_traverse;
      GType argument_table_traverse_gtype;
      gboolean deprecated;
      void (* _vips_reserved1) (
    void
      );
      void (* _vips_reserved2) (
    void
      );
      void (* _vips_reserved3) (
    void
      );
      void (* _vips_reserved4) (
    void
      );

    }

No description available.

###### Class members

`parent_class: GObjectClass`

  No description available.

`build: int (* build) ( VipsObject* object )`

  No description available.

`postbuild: int (* postbuild) ( VipsObject* object, void* data )`

  No description available.

`summary_class: void (* summary_class) ( _VipsObjectClass* cls, VipsBuf* buf )`

  No description available.

`summary: void (* summary) ( VipsObject* object, VipsBuf* buf )`

  No description available.

`dump: void (* dump) ( VipsObject* object, VipsBuf* buf )`

  No description available.

`sanity: void (* sanity) ( VipsObject* object, VipsBuf* buf )`

  No description available.

`rewind: void (* rewind) ( VipsObject* object )`

  No description available.

`preclose: void (* preclose) ( VipsObject* object )`

  No description available.

`close: void (* close) ( VipsObject* object )`

  No description available.

`postclose: void (* postclose) ( VipsObject* object )`

  No description available.

`new_from_string: VipsObject* (* new_from_string) ( const char* string )`

  No description available.

`to_string: void (* to_string) ( VipsObject* object, VipsBuf* buf )`

  No description available.

`output_needs_arg: gboolean`

  No description available.

`output_to_arg: int (* output_to_arg) ( VipsObject* object, const char* string )`

  No description available.

`nickname: const char*`

  No description available.

`description: const char*`

  No description available.

`argument_table: VipsArgumentTable*`

  No description available.

`argument_table_traverse: gpointer`

  No description available.

`argument_table_traverse_gtype: GType`

  No description available.

`deprecated: gboolean`

  No description available.

`_vips_reserved1: void (* _vips_reserved1) ( void )`

  No description available.

`_vips_reserved2: void (* _vips_reserved2) ( void )`

  No description available.

`_vips_reserved3: void (* _vips_reserved3) ( void )`

  No description available.

`_vips_reserved4: void (* _vips_reserved4) ( void )`

  No description available.

#### Virtual methods

###### Vips.ObjectClass.build

No description available.

###### Vips.ObjectClass.close

No description available.

###### Vips.ObjectClass.dump

Dump everything that vips knows about an object to a string.

###### Vips.ObjectClass.output_to_arg

No description available.

###### Vips.ObjectClass.postbuild

No description available.

###### Vips.ObjectClass.postclose

No description available.

###### Vips.ObjectClass.preclose

No description available.

###### Vips.ObjectClass.rewind

No description available.

###### Vips.ObjectClass.sanity

No description available.

###### Vips.ObjectClass.summary

Generate a human-readable summary for an object.

###### Vips.ObjectClass.to_string

The inverse of `vips_object_new_from_string()`: turn `object` into eg. `"bicubic"`.

#### Class methods

###### vips_object_class_install_argument

No description available.