Class: Vips::MutableImage

Inherits:

Object

• Object
• GObject::GObject
• Object
• Vips::MutableImage

Extended by:

Forwardable

Defined in:

lib/vips/mutableimage.rb

Overview

This class represents a libvips image which can be modified. See Image#mutate.

Defined Under Namespace

Modules: MutableImageLayout Classes: ManagedStruct, Struct

Instance Attribute Summary

• #image ⇒ Object readonly

  Get the Image this MutableImage is modifying.

Attributes inherited from GObject::GObject

#ptr, #references

Instance Method Summary

• #draw_point!(ink, left, top, **opts) ⇒ Object

  Draw a point on an image.

• #initialize(image) ⇒ MutableImage constructor

  Make a MutableImage from a regular Image.

• #inspect ⇒ Object
• #method_missing(name, *args, **options) ⇒ Object

  Invoke a vips operation with Operation#call, using self as the first input argument.

• #remove!(name) ⇒ Object

  Remove a metadata item from an image.

• #respond_to?(name, include_all = false) ⇒ Boolean
• #respond_to_missing?(name, include_all = false) ⇒ Boolean
• #set!(name, value) ⇒ Object

  Set the value of a metadata item on an image.

• #set_type!(gtype, name, value) ⇒ Object

  Create a metadata item on an image of the specifed type.

Methods inherited from Object

#get, #get_pspec, #get_typeof, #get_typeof_error, print_all, #set, #signal_connect

Methods inherited from GObject::GObject

#ffi_managed_struct, ffi_managed_struct, ffi_struct, #ffi_struct

Constructor Details

#initialize(image) ⇒ MutableImage

Make a Vips::MutableImage from a regular Image.

This is for internal use only. See Image#mutate for the user-facing interface.

# File 'lib/vips/mutableimage.rb', line 50

def initialize(image)
  # We take a copy of the regular Image to ensure we have an unshared
  # (unique) object. We forward things like #width and #height to this, and
  # it's the thing we return at the end of the mutate block.
  copy_image = image.copy

  # Use ptr since we need the raw unwrapped pointer inside the image ...
  # and make the ref that gobject will unref when it finishes.
  # See also the comment on set_type! before changing this.
  pointer = copy_image.ptr
  ::GObject.g_object_ref pointer
  super(pointer)

  # and save the copy ready for when we finish mutating
  @image = copy_image
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(name, *args, **options) ⇒ Object

Invoke a vips operation with Operation#call, using self as the first input argument. Operation#call will only allow operations that modify self when passed a Vips::MutableImage.

Parameters:

• name (String) —

  vips operation to call

Returns:

• result of vips operation

# File 'lib/vips/mutableimage.rb', line 95

def method_missing name, *args, **options
  Vips::Operation.call name.to_s, [self, *args], options
end

Instance Attribute Details

#image ⇒ Object (readonly)

Get the Image this Vips::MutableImage is modifying. Only use this once you have finished all modifications.

This is for internal use only. See Image#mutate for the user-facing interface.

# File 'lib/vips/mutableimage.rb', line 44

def image
  @image
end

Instance Method Details

#draw_point!(ink, left, top, **opts) ⇒ Object

Draw a point on an image.

See Image#draw_rect.

# File 'lib/vips/mutableimage.rb', line 102

def draw_point! ink, left, top, **opts
  draw_rect! ink, left, top, 1, 1, **opts
end

#inspect ⇒ Object

# File 'lib/vips/mutableimage.rb', line 67

def inspect
  "#<MutableImage #{width}x#{height} #{format}, #{bands} bands, #{interpretation}>"
end

#remove!(name) ⇒ Object

Remove a metadata item from an image.

For example:

x.remove! "icc-profile-data"

Parameters:

• name (String) —

  Metadata field to remove

# File 'lib/vips/mutableimage.rb', line 172

def remove! name
  # See set_type! for an explanation. Image#remove can't throw an
  # exception, so there's no need to ensure we unref.
  ::GObject.g_object_unref ptr
  Vips.vips_image_remove self, name
  ::GObject.g_object_ref ptr
end

#respond_to?(name, include_all = false) ⇒ Boolean

Returns:

• (Boolean)

# File 'lib/vips/mutableimage.rb', line 71

def respond_to? name, include_all = false
  # To support keyword args, we need to tell Ruby that final image
  # arguments cannot be hashes of keywords.
  #
  # https://makandracards.com/makandra/
  #   36013-heads-up-ruby-implicitly-converts-a-hash-to-keyword-arguments
  return false if name == :to_hash

  super
end

#respond_to_missing?(name, include_all = false) ⇒ Boolean

Returns:

• (Boolean)

# File 'lib/vips/mutableimage.rb', line 82

def respond_to_missing? name, include_all = false
  # Respond to all vips operations by nickname.
  return true if Vips.type_find("VipsOperation", name.to_s) != 0

  super
end

#set!(name, value) ⇒ Object

Set the value of a metadata item on an image. The metadata item must already exist. Ruby types are automatically transformed into the matching GObject::GValue, if possible.

For example, you can use this to set an image's ICC profile:

x.set! "icc-profile-data", profile

where profile is an ICC profile held as a binary string object.

Parameters:

• name (String) —

  Metadata field to set

• value (Object) —

  Value to set

See Also:

• #set_type!

# File 'lib/vips/mutableimage.rb', line 159

def set! name, value
  set_type! get_typeof(name), name, value
end

#set_type!(gtype, name, value) ⇒ Object

Create a metadata item on an image of the specifed type. Ruby types are automatically transformed into the matching glib type (eg. GObject::GINT_TYPE), if possible.

For example, you can use this to set an image's ICC profile:

x.set_type! Vips::BLOB_TYPE, "icc-profile-data", profile

where profile is an ICC profile held as a binary string object.

Parameters:

• gtype (Integer) —

  GType of item

• name (String) —

  Metadata field to set

• value (Object) —

  Value to set

See Also:

• #set!

# File 'lib/vips/mutableimage.rb', line 122

def set_type! gtype, name, value
  gvalue = GObject::GValue.alloc
  gvalue.init gtype
  gvalue.set value

  # libvips 8.9.1 had a terrible misfeature which would block metadata
  # modification unless the object had a ref_count of 1. MutableImage
  # will always have a ref_count of at least 2 (the parent gobject keeps a
  # ref, and we keep a ref to the copy ready to return to our caller),
  # so we must temporarily drop the refs to 1 around metadata changes.
  #
  # See https://github.com/libvips/ruby-vips/issues/291
  begin
    ::GObject.g_object_unref ptr
    Vips.vips_image_set self, name, gvalue
  ensure
    ::GObject.g_object_ref ptr
  end

  gvalue.unset
end