class Vips::MutableImage

This class represents a libvips image which can be modified. See {Vips::Image#mutate}.

Attributes

image[R]

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

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

Public Class Methods

new(image) click to toggle source

Make a {MutableImage} from a regular {Image}.

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

Calls superclass method GObject::GObject::new
# 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

Public Instance Methods

inspect() click to toggle source
# File lib/vips/mutableimage.rb, line 67
def inspect
  "#<MutableImage #{width}x#{height} #{format}, #{bands} bands, #{interpretation}>"
end
method_missing(name, *args, **options) click to toggle source

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

@param name [String] vips operation to call @return 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
remove!(name) click to toggle source

Remove a metadata item from an image.

For example:

“` x.remove! “icc-profile-data” “`

@param name [String] Metadata field to remove

# File lib/vips/mutableimage.rb, line 165
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) click to toggle source
Calls superclass method
# 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) click to toggle source
Calls superclass method
# 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) click to toggle source

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.

@see set_type! @param name [String] Metadata field to set @param value [Object] Value to set

# File lib/vips/mutableimage.rb, line 152
def set! name, value
  set_type! get_typeof(name), name, value
end
set_type!(gtype, name, value) click to toggle source

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:

“`ruby x.set_type! Vips::BLOB_TYPE, “icc-profile-data”, profile “`

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

@see set! @param gtype [Integer] GType of item @param name [String] Metadata field to set @param value [Object] Value to set

# File lib/vips/mutableimage.rb, line 115
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