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:

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.
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.
vips_object_build(). Call this to construct the object and get it ready for use. Building an object happens in four stages, see below.
g_object_get(). The object has now been built. You can read out any computed values.
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:

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.
The innermost build method inside VipsObject itself checks that all input arguments have been set and then returns.
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.
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:

VipsObject::preclose. This is emitted at the start of the VipsObject dispose. The object is still functioning.
VipsObject::close. This runs just after all VipsArgument held by the object have been released.
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.

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

Constructors

vips_object_new

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

Functions

vips_object_map

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

vips_object_print_summary_class

No description available.

vips_object_summary_class

Generate a human-readable summary for a class.

Instance methods

vips_object_argument_needsstring

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.

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. "VipsInterpolateSnohalo1(blur=.333333)".

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;
  GSList* 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: GSList*: 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.

Class methods

vips_object_class_install_argument

No description available.

Description [src]

The VipsObject lifecycle

The VipsObject reference counting convention

Hierarchy

Ancestors

Descendants

Constructors

Functions

Instance methods

Methods inherited from GObject (43)

Properties

Signals

Signals inherited from GObject (1)

Class structure

Class members

Virtual methods

Class methods

The `VipsObject` lifecycle

The `VipsObject` reference counting convention