vips 8.10.5 → 8.12.2

data/lib/vips/mutableimage.rb

@@ -0,0 +1,180 @@
+# This module provides an interface to the vips image processing library
+# via ruby-ffi.
+#
+# Author::    John Cupitt  (mailto:jcupitt@gmail.com)
+# License::   MIT
+
+require "ffi"
+require "forwardable"
+
+module Vips
+  # This class represents a libvips image which can be modified. See
+  # {Vips::Image#mutate}.
+  class MutableImage < Vips::Object
+    extend Forwardable
+    alias_method :parent_get_typeof, :get_typeof
+    def_instance_delegators :@image, :width, :height, :bands, :format,
+      :interpretation, :filename, :xoffset, :yoffset, :xres, :yres, :size,
+      :get, :get_typeof, :get_fields
+
+    # layout is exactly as {Image} (since we are also wrapping a VipsImage
+    # object)
+    module MutableImageLayout
+      def self.included base
+        base.class_eval do
+          layout :parent, Vips::Object::Struct
+          # rest opaque
+        end
+      end
+    end
+
+    class Struct < Vips::Object::Struct
+      include MutableImageLayout
+    end
+
+    class ManagedStruct < Vips::Object::ManagedStruct
+      include MutableImageLayout
+    end
+
+    # 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.
+    attr_reader :image
+
+    # Make a {MutableImage} from a regular {Image}.
+    #
+    # This is for internal use only. See {Vips::Image#mutate} for the
+    # user-facing interface.
+    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
+
+    def inspect
+      "#<MutableImage #{width}x#{height} #{format}, #{bands} bands, #{interpretation}>"
+    end
+
+    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
+
+    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
+
+    # 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
+    def method_missing name, *args, **options
+      Vips::Operation.call name.to_s, [self, *args], options
+    end
+
+    # Draw a point on an image.
+    #
+    # See {Image#draw_rect}.
+    def draw_point! ink, left, top, **opts
+      draw_rect! ink, left, top, 1, 1, **opts
+    end
+
+    # 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
+    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
+
+    # 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
+    def set! name, value
+      set_type! get_typeof(name), name, value
+    end
+
+    # Remove a metadata item from an image.
+    #
+    # For example:
+    #
+    # ```
+    # x.remove! "icc-profile-data"
+    # ```
+    #
+    # @param name [String] Metadata field to remove
+    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
+  end
+end

data/lib/vips/object.rb

@@ -4,7 +4,7 @@
 # Author::    John Cupitt  (mailto:jcupitt@gmail.com)
 # License::   MIT
 
-require 'ffi'
+require "ffi"
 
 module Vips
   private
@@ -21,20 +21,20 @@ module Vips
   public
 
   # some handy gtypes
-  IMAGE_TYPE = GObject::g_type_from_name "VipsImage"
-  ARRAY_INT_TYPE = GObject::g_type_from_name "VipsArrayInt"
-  ARRAY_DOUBLE_TYPE = GObject::g_type_from_name "VipsArrayDouble"
-  ARRAY_IMAGE_TYPE = GObject::g_type_from_name "VipsArrayImage"
-  REFSTR_TYPE = GObject::g_type_from_name "VipsRefString"
-  BLOB_TYPE = GObject::g_type_from_name "VipsBlob"
-
-  BAND_FORMAT_TYPE = Vips::vips_band_format_get_type
-  INTERPRETATION_TYPE = Vips::vips_interpretation_get_type
-  CODING_TYPE = Vips::vips_coding_get_type
-
-  if Vips::at_least_libvips?(8, 6)
+  IMAGE_TYPE = GObject.g_type_from_name "VipsImage"
+  ARRAY_INT_TYPE = GObject.g_type_from_name "VipsArrayInt"
+  ARRAY_DOUBLE_TYPE = GObject.g_type_from_name "VipsArrayDouble"
+  ARRAY_IMAGE_TYPE = GObject.g_type_from_name "VipsArrayImage"
+  REFSTR_TYPE = GObject.g_type_from_name "VipsRefString"
+  BLOB_TYPE = GObject.g_type_from_name "VipsBlob"
+
+  BAND_FORMAT_TYPE = Vips.vips_band_format_get_type
+  INTERPRETATION_TYPE = Vips.vips_interpretation_get_type
+  CODING_TYPE = Vips.vips_coding_get_type
+
+  if Vips.at_least_libvips?(8, 6)
     attach_function :vips_blend_mode_get_type, [], :GType
-    BLEND_MODE_TYPE = Vips::vips_blend_mode_get_type
+    BLEND_MODE_TYPE = Vips.vips_blend_mode_get_type
   else
     BLEND_MODE_TYPE = nil
   end
@@ -45,37 +45,34 @@ module Vips
     layout :im, :pointer,
       :run, :int,
       :eta, :int,
-      :tpels, :int64_t, 
-      :npels, :int64_t, 
-      :percent, :int, 
-      :start, :pointer 
+      :tpels, :int64_t,
+      :npels, :int64_t,
+      :percent, :int,
+      :start, :pointer
   end
 
-  # Our signal marshalers. 
+  # Our signal marshalers.
   #
-  # These are functions which take the handler as a param and return a 
+  # These are functions which take the handler as a param and return a
   # closure with the right FFI signature for g_signal_connect for this
-  # specific signal. 
+  # specific signal.
   #
-  # ruby-ffi makes it hard to use the g_signal_connect user data param 
+  # ruby-ffi makes it hard to use the g_signal_connect user data param
   # to pass the function pointer through, unfortunately.
   #
   # We can't throw exceptions across C, so we must catch everything.
 
-  MARSHAL_PROGRESS = Proc.new do |handler|
+  MARSHAL_PROGRESS = proc do |handler|
     FFI::Function.new(:void, [:pointer, :pointer, :pointer]) do |vi, prog, cb|
-      begin
-        handler.(Progress.new(prog))
-      rescue Exception => e
-        puts "progress: #{e}"
-      end
+      # this can't throw an exception, so no catch is necessary
+      handler.call(Progress.new(prog))
     end
   end
 
-  MARSHAL_READ = Proc.new do |handler|
+  MARSHAL_READ = proc do |handler|
     FFI::Function.new(:int64_t, [:pointer, :pointer, :int64_t]) do |i, p, len|
       begin
-        result = handler.(p, len)
+        result = handler.call(p, len)
       rescue Exception => e
         puts "read: #{e}"
         result = 0
@@ -85,10 +82,10 @@ module Vips
     end
   end
 
-  MARSHAL_SEEK = Proc.new do |handler|
+  MARSHAL_SEEK = proc do |handler|
     FFI::Function.new(:int64_t, [:pointer, :int64_t, :int]) do |i, off, whence|
       begin
-        result = handler.(off, whence)
+        result = handler.call(off, whence)
       rescue Exception => e
         puts "seek: #{e}"
         result = -1
@@ -98,10 +95,10 @@ module Vips
     end
   end
 
-  MARSHAL_WRITE = Proc.new do |handler|
+  MARSHAL_WRITE = proc do |handler|
     FFI::Function.new(:int64_t, [:pointer, :pointer, :int64_t]) do |i, p, len|
       begin
-        result = handler.(p, len)
+        result = handler.call(p, len)
       rescue Exception => e
         puts "write: #{e}"
         result = 0
@@ -111,41 +108,38 @@ module Vips
     end
   end
 
-  MARSHAL_FINISH = Proc.new do |handler|
+  MARSHAL_FINISH = proc do |handler|
     FFI::Function.new(:void, [:pointer, :pointer]) do |i, cb|
-      begin
-        handler.()
-      rescue Exception => e
-        puts "finish: #{e}"
-      end
+      # this can't throw an exception, so no catch is necessary
+      handler.call
     end
   end
 
   # map signal name to marshal proc
   MARSHAL_ALL = {
-    :preeval => MARSHAL_PROGRESS,
-    :eval => MARSHAL_PROGRESS,
-    :posteval => MARSHAL_PROGRESS,
-    :read => MARSHAL_READ,
-    :seek => MARSHAL_SEEK,
-    :write => MARSHAL_WRITE,
-    :finish => MARSHAL_FINISH,
+    preeval: MARSHAL_PROGRESS,
+    eval: MARSHAL_PROGRESS,
+    posteval: MARSHAL_PROGRESS,
+    read: MARSHAL_READ,
+    seek: MARSHAL_SEEK,
+    write: MARSHAL_WRITE,
+    finish: MARSHAL_FINISH
   }
 
   attach_function :vips_enum_from_nick, [:string, :GType, :string], :int
   attach_function :vips_enum_nick, [:GType, :int], :string
 
   attach_function :vips_value_set_ref_string,
-      [GObject::GValue.ptr, :string], :void
+    [GObject::GValue.ptr, :string], :void
   attach_function :vips_value_set_array_double,
-      [GObject::GValue.ptr, :pointer, :int], :void
+    [GObject::GValue.ptr, :pointer, :int], :void
   attach_function :vips_value_set_array_int,
-      [GObject::GValue.ptr, :pointer, :int], :void
+    [GObject::GValue.ptr, :pointer, :int], :void
   attach_function :vips_value_set_array_image,
-      [GObject::GValue.ptr, :int], :void
+    [GObject::GValue.ptr, :int], :void
   callback :free_fn, [:pointer], :void
   attach_function :vips_value_set_blob,
-      [GObject::GValue.ptr, :free_fn, :pointer, :size_t], :void
+    [GObject::GValue.ptr, :free_fn, :pointer, :size_t], :void
 
   class SizeStruct < FFI::Struct
     layout :value, :size_t
@@ -156,15 +150,15 @@ module Vips
   end
 
   attach_function :vips_value_get_ref_string,
-      [GObject::GValue.ptr, SizeStruct.ptr], :string
+    [GObject::GValue.ptr, SizeStruct.ptr], :string
   attach_function :vips_value_get_array_double,
-      [GObject::GValue.ptr, IntStruct.ptr], :pointer
+    [GObject::GValue.ptr, IntStruct.ptr], :pointer
   attach_function :vips_value_get_array_int,
-      [GObject::GValue.ptr, IntStruct.ptr], :pointer
+    [GObject::GValue.ptr, IntStruct.ptr], :pointer
   attach_function :vips_value_get_array_image,
-      [GObject::GValue.ptr, IntStruct.ptr], :pointer
+    [GObject::GValue.ptr, IntStruct.ptr], :pointer
   attach_function :vips_value_get_blob,
-      [GObject::GValue.ptr, SizeStruct.ptr], :pointer
+    [GObject::GValue.ptr, SizeStruct.ptr], :pointer
 
   attach_function :type_find, :vips_type_find, [:string, :string], :GType
 
@@ -173,7 +167,7 @@ module Vips
     # debugging ruby-vips.
     def self.print_all
       GC.start
-      Vips::vips_object_print_all
+      Vips.vips_object_print_all
     end
 
     # the layout of the VipsObject struct
@@ -182,15 +176,15 @@ module Vips
         base.class_eval do
           # don't actually need most of these
           layout :parent, GObject::GObject::Struct,
-             :constructed, :int,
-             :static_object, :int,
-             :argument_table, :pointer,
-             :nickname, :string,
-             :description, :string,
-             :preclose, :int,
-             :close, :int,
-             :postclose, :int,
-             :local_memory, :size_t
+            :constructed, :int,
+            :static_object, :int,
+            :argument_table, :pointer,
+            :nickname, :string,
+            :description, :string,
+            :preclose, :int,
+            :close, :int,
+            :postclose, :int,
+            :local_memory, :size_t
         end
       end
     end
@@ -210,8 +204,8 @@ module Vips
       argument_class = Vips::ArgumentClassPtr.new
       argument_instance = Vips::ArgumentInstancePtr.new
 
-      result = Vips::vips_object_get_argument self, name,
-          ppspec, argument_class, argument_instance
+      result = Vips.vips_object_get_argument self, name,
+        ppspec, argument_class, argument_instance
       return nil if result != 0
 
       ppspec[:value]
@@ -229,7 +223,7 @@ module Vips
     def get_typeof name
       pspec = get_pspec name
       unless pspec
-        Vips::vips_error_clear
+        Vips.vips_error_clear
         return 0
       end
 
@@ -240,44 +234,43 @@ module Vips
       gtype = get_typeof_error name
       gvalue = GObject::GValue.alloc
       gvalue.init gtype
-      GObject::g_object_get_property self, name, gvalue
+      GObject.g_object_get_property self, name, gvalue
       result = gvalue.get
       gvalue.unset
 
-      GLib::logger.debug("Vips::Object.get") { "#{name} == #{result}" }
+      GLib.logger.debug("Vips::Object.get") { "#{name} == #{result}" }
 
-      return result
+      result
     end
 
     def set name, value
-      GLib::logger.debug("Vips::Object.set") { "#{name} = #{value}" }
+      GLib.logger.debug("Vips::Object.set") { "#{name} = #{value}" }
 
       gtype = get_typeof_error name
       gvalue = GObject::GValue.alloc
       gvalue.init gtype
       gvalue.set value
-      GObject::g_object_set_property self, name, gvalue
+      GObject.g_object_set_property self, name, gvalue
       gvalue.unset
     end
 
-    def signal_connect name, handler=nil, &block
+    def signal_connect name, handler = nil, &block
       marshal = MARSHAL_ALL[name.to_sym]
-      raise Vips::Error, "unsupported signal #{name}" if marshal == nil
+      raise Vips::Error, "unsupported signal #{name}" if marshal.nil?
 
       unless handler ||= block
         raise Vips::Error, "must supply either block or handler"
       end
 
-      # The marshal function will make a closure with the right type signature 
+      # The marshal function will make a closure with the right type signature
       # for the selected signal
       callback = marshal.(handler)
 
       # we need to make sure this is not GCd while self is alive
       @references << callback
 
-      GObject::g_signal_connect_data(self, name.to_s, callback, nil, nil, 0)
+      GObject.g_signal_connect_data(self, name.to_s, callback, nil, nil, 0)
     end
-
   end
 
   class ObjectClass < FFI::Struct
@@ -316,10 +309,10 @@ module Vips
 
   class ArgumentClass < Argument
     layout :parent, Argument,
-           :object_class, ObjectClass.ptr,
-           :flags, :uint,
-           :priority, :int,
-           :offset, :ulong_long
+      :object_class, ObjectClass.ptr,
+      :flags, :uint,
+      :priority, :int,
+      :offset, :ulong_long
   end
 
   class ArgumentClassPtr < FFI::Struct
@@ -333,10 +326,10 @@ module Vips
   # just use :pointer, not VipsObject.ptr, to avoid casting gobject
   # subclasses
   attach_function :vips_object_get_argument,
-      [:pointer, :string,
-       GObject::GParamSpecPtr.ptr,
-       ArgumentClassPtr.ptr, ArgumentInstancePtr.ptr],
-      :int
+    [:pointer, :string,
+      GObject::GParamSpecPtr.ptr,
+      ArgumentClassPtr.ptr, ArgumentInstancePtr.ptr],
+    :int
 
   attach_function :vips_object_set_from_string, [:pointer, :string], :int