Vips.Object¶

Subclasses:: Vips.Connection, Vips.Image, Vips.Interpolate, Vips.Operation, Vips.Region, Vips.Sbuf, Vips.ThreadState

Methods¶

Inherited:: GObject.Object (37)
Structs:: Vips.ObjectClass (1), GObject.ObjectClass (5)

class	`get_property` (gobject, property_id, value, pspec)
class	`install_argument` (pspec, flags, priority, offset)
class	`new_from_string` (object_class, p)
class	`print_all` ()
class	`print_summary_class` (klass)
class	`sanity_all` ()
class	`set_property` (gobject, property_id, value, pspec)
	`argument_isset` (name)
	`argument_needsstring` (name)
	`build` ()
	`get_argument_flags` (name)
	`get_argument_priority` (name)
	`get_argument_to_string` (name, arg)
	`get_description` ()
	`local_cb` (gobject)
	`preclose` ()
	`print_dump` ()
	`print_name` ()
	`print_summary` ()
	`rewind` ()
	`sanity` ()
	`set_argument_from_string` (name, value)
	`set_from_string` (string)
	`set_required` (value)
	`set_static` (static_object)
	`to_string` (buf)
	`unref_outputs` ()

Virtual Methods¶

Inherited:: GObject.Object (7)

	`do_build` ()
	`do_close` ()
	`do_output_to_arg` (string)
	`do_postbuild` (data)
	`do_postclose` ()
	`do_preclose` ()
	`do_rewind` ()
	`do_sanity` (buf)
	`do_to_string` (buf)

Properties¶

Name	Type	Flags	Short Description
`description`	`str`	r/w	Class description
`nickname`	`str`	r/w	Class nickname

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`close`	The `::close` signal is emitted once during object close.
`postbuild`	The `::postbuild` signal is emitted once just after successful object construction.
`postclose`	The `::postclose` signal is emitted once after object close.
`preclose`	The `::preclose` signal is emitted once just before object close starts.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access
argument_table	{`object`: `object`}	r
close	`bool`	r
constructed	`bool`	r
description	`str`	r
local_memory	`int`	r
nickname	`str`	r
parent_instance	`GObject.Object`	r
postclose	`bool`	r
static_object	`bool`	r

Class Details¶

class Vips.Object(**kwargs)¶

Bases:: GObject.Object
Abstract:: Yes
Structure:: Vips.ObjectClass

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 [class`Object`] lifecycle

[class`Object`]’s have a strictly defined lifecycle, split broadly as construct and then use. In detail, the stages are:

[ctor`GObject`.Object.new]. The [class`Object`] is created with [ctor`GObject`.Object.new]. Objects in this state are blank slates and need to have their various parameters set.

[method`GObject`.Object.set]. You loop over the [struct`Argument`] that the object has defined with [func`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.

[method`Object`.build]. Call this to construct the object and get it ready for use. Building an object happens in four stages, see below.

[method`GObject`.Object.get]. The object has now been built. You can read out any computed values.

[method`GObject`.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 [class`Object`] uses. When the last ref to an object is released, the object is closed. Objects close in three stages, see below.

The stages inside [method`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 [class`Object`] 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.

[method`Object`.build] finishes the process by checking that all output objects have been set, and then triggering the [signal`Object`:py:func:::postbuild<Vips.Object.signals.postbuild>] signal. [signal`Object`:py:func:::postbuild<Vips.Object.signals.postbuild>] only runs if the object has constructed successfully.

[class`Operation`] has a cache of recent operation objects, see that class for an explanation of [func`cache_operation_build`].

Finally, the stages inside close are:

[signal`Object`:py:func:::preclose<Vips.Object.signals.preclose>]. This is emitted at the start of the [class`Object`] dispose. The object is still functioning.

[signal`Object`:py:func:::close<Vips.Object.signals.close>]. This runs just after all [struct`Argument`] held by the object have been released.

[signal`Object`:py:func:::postclose<Vips.Object.signals.postclose>]. This runs right at the end. The object pointer is still valid, but nothing else is.

The [class`Object`] reference counting convention

[class`Object`] has a set of conventions to simplify reference counting.

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

All output [class`GObject`.Object] hold a ref to the object. When a [class`GObject`.Object] which is an output of a [class`Object`] is disposed, it must drop this reference. [class`Object`] which are outputs of other [class`Object`]’s will do this automatically.

See [class`Operation`] for an example of [class`Object`] reference counting.

classmethod get_property(gobject, property_id, value, pspec)¶

Parameters:

gobject (GObject.Object) –
property_id (int) –
value (GObject.Value) –
pspec (GObject.ParamSpec) –

classmethod install_argument(pspec, flags, priority, offset)¶

Parameters:

pspec (GObject.ParamSpec) –
flags (Vips.ArgumentFlags) –
priority (int) –
offset (int) –

classmethod new_from_string(object_class, p)¶

Parameters:

object_class (Vips.ObjectClass) –
p (str) –

Return type:

Vips.Object

classmethod print_all()¶

classmethod print_summary_class(klass)¶

Parameters:: klass (Vips.ObjectClass) –

classmethod sanity_all()¶

classmethod set_property(gobject, property_id, value, pspec)¶

Parameters:

gobject (GObject.Object) –
property_id (int) –
value (GObject.Value) –
pspec (GObject.ParamSpec) –

argument_isset(name)¶

Parameters:: name (str) – arg to fetch
Returns:: TRUE if the argument has been assigned.
Return type:: bool

Convenience: has an argument been assigned. Useful for bindings.

argument_needsstring(name)¶

Parameters:: name (str) –
Return type:: bool

build()¶

Return type:: int

get_argument_flags(name)¶

Parameters:: name (str) – arg to fetch
Returns:: The [flags`ArgumentFlags`] for this argument.
Return type:: Vips.ArgumentFlags

Convenience: get the flags for an argument. Useful for bindings.

get_argument_priority(name)¶

Parameters:: name (str) – arg to fetch
Returns:: The priority of this argument.
Return type:: int

Convenience: get the priority for an argument. Useful for bindings.

get_argument_to_string(name, arg)¶

Parameters:

name (str) –
arg (str) –

Return type:

int

get_description()¶

Returns:: the object description
Return type:: str

Fetch the object description. Useful for language bindings.

[property`Object`:py:data::description<Vips.Object.props.description>] is only available after _build(), which can be too late. This function fetches from the instance, if possible, but falls back to the class description if we are too early.

local_cb(gobject)¶

Parameters:: gobject (GObject.Object) –

preclose()¶

print_dump()¶

print_name()¶

print_summary()¶

rewind()¶

sanity()¶

Return type:: bool

set_argument_from_string(name, value)¶

Parameters:

name (str) –
value (str) –

Return type:

int

set_from_string(string)¶

Parameters:: string (str) – arguments as a string
Returns:: 0 on success, -1 on error
Return type:: int

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.

You’d typically use this between creating the object and building it.

::: seealso [method`Object`.set], [method`Object`.build], [func`cache_operation_buildp`].

set_required(value)¶

Parameters:: value (str) –
Return type:: int

set_static(static_object)¶

Parameters:: static_object (bool) –

to_string(buf)¶

Parameters:: buf (Vips.Buf) – write string here

The inverse of [ctor`Object`.new_from_string]: turn self into eg. "VipsInterpolateSnohalo1(blur=.333333)".

unref_outputs()¶

Unref all assigned output objects. Useful for language bindings.

After an object is built, all output args are owned by the caller. If something goes wrong before then, we have to unref the outputs that have been made so far. This function can also be useful for callers when they’ve finished processing outputs themselves.

::: seealso [func`cache_operation_build`].

do_build() virtual¶

Return type:: int

do_close() virtual¶

do_output_to_arg(string) virtual¶

Parameters:: string (str) –
Return type:: int

do_postbuild(data) virtual¶

Parameters:: data (object or None) –
Return type:: int

do_postclose() virtual¶

do_preclose() virtual¶

do_rewind() virtual¶

do_sanity(buf) virtual¶

Parameters:: buf (Vips.Buf) –

do_to_string(buf) virtual¶

Parameters:: buf (Vips.Buf) – write string here

The inverse of [ctor`Object`.new_from_string]: turn object into eg. "VipsInterpolateSnohalo1(blur=.333333)".

Signal Details¶

Vips.Object.signals.close(object)¶

Signal Name:: close
Flags:: RUN_LAST
Parameters:: object (Vips.Object) – The object which received the signal

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

Vips.Object.signals.postbuild(object)¶

Signal Name:: postbuild
Flags:: RUN_LAST
Parameters:: object (Vips.Object) – The object which received the signal
Return type:: int

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

Vips.Object.signals.postclose(object)¶

Signal Name:: postclose
Flags:: RUN_LAST
Parameters:: object (Vips.Object) – The object which received the signal

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

Vips.Object.signals.preclose(object)¶

Signal Name:: preclose
Flags:: RUN_LAST
Parameters:: object (Vips.Object) – The object which received the signal

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

Property Details¶

Vips.Object.props.description¶

Name:: description
Type:: str
Default Value:: ''
Flags:: READABLE, WRITABLE

Class description

Vips.Object.props.nickname¶

Name:: nickname
Type:: str
Default Value:: ''
Flags:: READABLE, WRITABLE

Class nickname