vips 8.11.3 → 8.12.1

data/lib/vips/operation.rb

@@ -4,7 +4,8 @@
 # Author::    John Cupitt  (mailto:jcupitt@gmail.com)
 # License::   MIT
 
-require 'ffi'
+require "ffi"
+require "set"
 
 module Vips
   private
@@ -12,22 +13,22 @@ module Vips
   attach_function :vips_operation_new, [:string], :pointer
 
   # We may well block during this (eg. if it's avg, or perhaps jpegsave), and
-  # libvips might trigger some signals which ruby has handles for. 
+  # libvips might trigger some signals which ruby has handles for.
   #
-  # We need FFI to drop the GIL lock during this call and reacquire it when 
+  # We need FFI to drop the GIL lock during this call and reacquire it when
   # the call ends, or we'll deadlock.
-  attach_function :vips_cache_operation_build, [:pointer], :pointer, 
+  attach_function :vips_cache_operation_build, [:pointer], :pointer,
     blocking: true
   attach_function :vips_object_unref_outputs, [:pointer], :void
 
   callback :argument_map_fn, [:pointer,
-                              GObject::GParamSpec.ptr,
-                              ArgumentClass.ptr,
-                              ArgumentInstance.ptr,
-                              :pointer, :pointer], :pointer
+    GObject::GParamSpec.ptr,
+    ArgumentClass.ptr,
+    ArgumentInstance.ptr,
+    :pointer, :pointer], :pointer
   attach_function :vips_argument_map, [:pointer,
-                                       :argument_map_fn,
-                                       :pointer, :pointer], :pointer
+    :argument_map_fn,
+    :pointer, :pointer], :pointer
 
   OPERATION_SEQUENTIAL = 1
   OPERATION_NOCACHE = 4
@@ -45,14 +46,26 @@ module Vips
   # everything we know about it. This is used for doc generation as well as
   # call.
   class Introspect
-    attr_reader :name, :description, :flags, :args, :required_input, 
-      :optional_input, :required_output, :optional_output, :member_x, 
-      :method_args
+    attr_reader :name, :description, :flags, :args, :required_input,
+      :optional_input, :required_output, :optional_output, :member_x,
+      :method_args, :vips_name, :destructive, :doc_optional_input,
+      :doc_optional_output
 
     @@introspect_cache = {}
 
     def initialize name
-      @op = Operation.new name
+      # if there's a trailing "!", this is a destructive version of an
+      # operation
+      if name[-1] == "!"
+        @destructive = true
+        # strip the trailing "!"
+        @vips_name = name[0...-1]
+      else
+        @destructive = false
+        @vips_name = name
+      end
+
+      @op = Operation.new @vips_name
       @args = []
       @required_input = []
       @optional_input = {}
@@ -66,12 +79,14 @@ module Vips
           # names can include - as punctuation, but we always use _ in
           # Ruby
           arg_name = pspec[:name].tr("-", "_")
-          args << {
-            :arg_name => arg_name,
-            :flags => flags,
-            :gtype => pspec[:value_type]
+          @args << {
+            arg_name: arg_name,
+            flags: flags,
+            gtype: pspec[:value_type]
           }
         end
+
+        nil
       end
 
       @args.each do |details|
@@ -79,26 +94,27 @@ module Vips
         flags = details[:flags]
 
         if (flags & ARGUMENT_INPUT) != 0
-          if (flags & ARGUMENT_REQUIRED) != 0 && 
-             (flags & ARGUMENT_DEPRECATED) == 0
+          if (flags & ARGUMENT_REQUIRED) != 0 &&
+              (flags & ARGUMENT_DEPRECATED) == 0
             @required_input << details
           else
             # we allow deprecated optional args
             @optional_input[arg_name] = details
           end
 
-          # MODIFY INPUT args count as OUTPUT as well
-          if (flags & ARGUMENT_MODIFY) != 0
-            if (flags & ARGUMENT_REQUIRED) != 0 && 
-               (flags & ARGUMENT_DEPRECATED) == 0
+          # MODIFY INPUT args count as OUTPUT as well in non-destructive mode
+          if (flags & ARGUMENT_MODIFY) != 0 &&
+              !@destructive
+            if (flags & ARGUMENT_REQUIRED) != 0 &&
+                (flags & ARGUMENT_DEPRECATED) == 0
               @required_output << details
             else
               @optional_output[arg_name] = details
             end
           end
         elsif (flags & ARGUMENT_OUTPUT) != 0
-          if (flags & ARGUMENT_REQUIRED) != 0 && 
-             (flags & ARGUMENT_DEPRECATED) == 0
+          if (flags & ARGUMENT_REQUIRED) != 0 &&
+              (flags & ARGUMENT_DEPRECATED) == 0
             @required_output << details
           else
             # again, allow deprecated optional args
@@ -106,6 +122,16 @@ module Vips
           end
         end
       end
+
+      # in destructive mode, the first required input arg must be MODIFY and
+      # must be an image
+      if @destructive
+        if @required_input.length < 1 ||
+            @required_input[0][:flags] & ARGUMENT_MODIFY == 0 ||
+            @required_input[0][:gtype] != IMAGE_TYPE
+          raise Vips::Error, "operation #{@vips_name} is not destructive"
+        end
+      end
     end
 
     # Yard comment generation needs a little more introspection. We add this
@@ -113,10 +139,12 @@ module Vips
     # we can.
     def add_yard_introspection name
       @name = name
-      @description = Vips::vips_object_get_description @op
-      @flags = Vips::vips_operation_get_flags @op
+      @description = Vips.vips_object_get_description @op
+      @flags = Vips.vips_operation_get_flags @op
       @member_x = nil
       @method_args = []
+      @doc_optional_input = {}
+      @doc_optional_output = {}
 
       @args.each do |details|
         arg_name = details[:arg_name]
@@ -125,20 +153,31 @@ module Vips
 
         details[:yard_name] = arg_name == "in" ? "im" : arg_name
         pspec = @op.get_pspec arg_name
-        details[:blurb] = GObject::g_param_spec_get_blurb pspec
+        details[:blurb] = GObject.g_param_spec_get_blurb pspec
 
-        if (flags & ARGUMENT_INPUT) != 0 && 
-           (flags & ARGUMENT_REQUIRED) != 0 && 
-           (flags & ARGUMENT_DEPRECATED) == 0
-          # the first required input image is the thing we will be a method 
+        if (flags & ARGUMENT_INPUT) != 0 &&
+            (flags & ARGUMENT_REQUIRED) != 0 &&
+            (flags & ARGUMENT_DEPRECATED) == 0
+          # the first required input image is the thing we will be a method
           # of
-          if @member_x == nil && gtype == IMAGE_TYPE
-            @member_x = details 
+          if @member_x.nil? && gtype == IMAGE_TYPE
+            @member_x = details
           else
             @method_args << details
           end
         end
       end
+
+      # and make the arg sets to document by filtering out deprecated args
+      @optional_input.each do |arg_name, details|
+        next if (details[:flags] & ARGUMENT_DEPRECATED) != 0
+        @doc_optional_input[details[:arg_name]] = details
+      end
+
+      @optional_output.each do |arg_name, details|
+        next if (details[:flags] & ARGUMENT_DEPRECATED) != 0
+        @doc_optional_output[details[:arg_name]] = details
+      end
     end
 
     def self.get name
@@ -150,7 +189,6 @@ module Vips
       introspect.add_yard_introspection name
       introspect
     end
-
   end
 
   class Operation < Object
@@ -176,7 +214,7 @@ module Vips
       # allow init with a pointer so we can wrap the return values from
       # things like _build
       if value.is_a? String
-        value = Vips::vips_operation_new value
+        value = Vips.vips_operation_new value
         raise Vips::Error if value.null?
       end
 
@@ -184,66 +222,65 @@ module Vips
     end
 
     def build
-      op = Vips::vips_cache_operation_build self
+      op = Vips.vips_cache_operation_build self
       if op.null?
-        Vips::vips_object_unref_outputs self
+        Vips.vips_object_unref_outputs self
         raise Vips::Error
       end
 
-      return Operation.new op
+      Operation.new op
     end
 
     def argument_map &block
-      fn = Proc.new do |_op, pspec, argument_class, argument_instance, _a, _b|
+      fn = proc do |_op, pspec, argument_class, argument_instance, _a, _b|
         block.call pspec, argument_class, argument_instance
       end
-
-      Vips::vips_argument_map self, fn, nil, nil
+      Vips.vips_argument_map self, fn, nil, nil
     end
 
-    # Search an object for the first element to match a predicate. Search 
+    # Search an object for the first element to match a predicate. Search
     # inside subarrays and sub-hashes. Equlvalent to x.flatten.find{}.
     def self.flat_find object, &block
       if object.respond_to? :each
-        object.each do |x| 
-          result = flat_find x, &block 
-          return result if result != nil
+        object.each do |x|
+          result = flat_find x, &block
+          return result unless result.nil?
         end
-      else
-        return object if yield object
+      elsif yield object
+        return object
       end
 
-      return nil
+      nil
     end
 
     # expand a constant into an image
     def self.imageize match_image, value
-      return value if value.is_a? Image
+      return value if value.is_a?(Image) || value.is_a?(MutableImage)
 
       # 2D array values become tiny 2D images
       # if there's nothing to match to, we also make a 2D image
-      if (value.is_a?(Array) && value[0].is_a?(Array)) || 
-         match_image == nil
-        return Image.new_from_array value
+      if (value.is_a?(Array) && value[0].is_a?(Array)) || match_image.nil?
+        Image.new_from_array value
       else
         # we have a 1D array ... use that as a pixel constant and
         # expand to match match_image
-        return match_image.new_from_image value
+        match_image.new_from_image value
       end
     end
 
     # set an operation argument, expanding constants and copying images as
     # required
-    def set name, value, match_image, flags, gtype
+    def set name, value, match_image, flags, gtype, destructive
       if gtype == IMAGE_TYPE
-        value = Operation::imageize match_image, value
+        value = Operation.imageize match_image, value
 
-        if (flags & ARGUMENT_MODIFY) != 0
-          # make sure we have a unique copy
+        # in non-destructive mode, make sure we have a unique copy
+        if (flags & ARGUMENT_MODIFY) != 0 &&
+            !destructive
           value = value.copy.copy_memory
         end
       elsif gtype == ARRAY_IMAGE_TYPE
-        value = value.map { |x| Operation::imageize match_image, x }
+        value = value.map { |x| Operation.imageize match_image, x }
       end
 
       super name, value
@@ -319,8 +356,8 @@ module Vips
     # the constant value 255.
 
     def self.call name, supplied, optional = {}, option_string = ""
-      GLib::logger.debug("Vips::VipsOperation.call") {
-        "name = #{name}, supplied = #{supplied}, " +
+      GLib.logger.debug("Vips::VipsOperation.call") {
+        "name = #{name}, supplied = #{supplied}, " \
           "optional = #{optional}, option_string = #{option_string}"
       }
 
@@ -329,20 +366,21 @@ module Vips
       required_output = introspect.required_output
       optional_input = introspect.optional_input
       optional_output = introspect.optional_output
+      destructive = introspect.destructive
 
       unless supplied.is_a? Array
-        raise Vips::Error, "unable to call #{name}: " +
-                           "argument array is not an array"
+        raise Vips::Error, "unable to call #{name}: " \
+          "argument array is not an array"
       end
       unless optional.is_a? Hash
-        raise Vips::Error, "unable to call #{name}: " +
-                           "optional arguments are not a hash"
+        raise Vips::Error, "unable to call #{name}: " \
+          "optional arguments are not a hash"
       end
 
       if supplied.length != required_input.length
-        raise Vips::Error, "unable to call #{name}: " +
-                           "you supplied #{supplied.length} arguments, " +
-                           "but operation needs " + "#{required_input.length}."
+        raise Vips::Error, "unable to call #{name}: " \
+          "you supplied #{supplied.length} arguments, " \
+          "but operation needs #{required_input.length}."
       end
 
       # all supplied_optional keys should be in optional_input or
@@ -352,8 +390,8 @@ module Vips
 
         unless optional_input.has_key?(arg_name) ||
             optional_output.has_key?(arg_name)
-          raise Vips::Error, "unable to call #{name}: " +
-                             "unknown option #{arg_name}"
+          raise Vips::Error, "unable to call #{name}: " \
+            "unknown option #{arg_name}"
         end
       end
 
@@ -362,17 +400,58 @@ module Vips
       #
       # look inside array and hash arguments, since we may be passing an
       # array of images
-      match_image = flat_find(supplied) { |value| value.is_a? Image }
+      #
+      # also enforce the rules around mutable and non-mutable images
+      match_image = nil
+      flat_find(supplied) do |value|
+        if match_image
+          # no non-first image arg can ever be mutable
+          if value.is_a?(MutableImage)
+            raise Vips::Error, "unable to call #{name}: " \
+              "only the first image argument can be mutable"
+          end
+        elsif destructive
+          if value.is_a?(Image)
+            raise Vips::Error, "unable to call #{name}: " \
+              "first image argument to a destructive " \
+              "operation must be mutable"
+          elsif value.is_a?(MutableImage)
+            match_image = value
+          end
+        elsif value.is_a?(MutableImage)
+          # non destructive operation, so no mutable images
+          raise Vips::Error, "unable to call #{name}: " \
+            "must not pass mutable images to " \
+            "non-destructive operations"
+        elsif value.is_a?(Image)
+          match_image = value
+        end
 
-      op = Operation.new name
+        # keep looping
+        false
+      end
+
+      op = Operation.new introspect.vips_name
 
       # set any string args first so they can't be overridden
-      if option_string != nil
-        if Vips::vips_object_set_from_string(op, option_string) != 0
+      unless option_string.nil?
+        if Vips.vips_object_set_from_string(op, option_string) != 0
           raise Vips::Error
         end
       end
 
+      # collect a list of all input references here
+      references = Set.new
+
+      add_reference = lambda do |x|
+        if x.is_a?(Vips::Image)
+          x.references.each do |i|
+            references << i
+          end
+        end
+        false
+      end
+
       # set all required inputs
       required_input.each_index do |i|
         details = required_input[i]
@@ -381,7 +460,8 @@ module Vips
         gtype = details[:gtype]
         value = supplied[i]
 
-        op.set arg_name, value, match_image, flags, gtype
+        flat_find value, &add_reference
+        op.set arg_name, value, match_image, flags, gtype, destructive
       end
 
       # set all optional inputs
@@ -395,16 +475,27 @@ module Vips
           flags = details[:flags]
           gtype = details[:gtype]
 
-          op.set arg_name, value, match_image, flags, gtype
+          flat_find value, &add_reference
+          op.set arg_name, value, match_image, flags, gtype, destructive
         end
       end
 
       op = op.build
 
+      # attach all input refs to output x
+      set_reference = lambda do |x|
+        if x.is_a? Vips::Image
+          x.references += references
+        end
+        false
+      end
+
       # get all required results
       result = []
       required_output.each do |details|
-        result << op.get(details[:arg_name])
+        value = details[:arg_name]
+        flat_find value, &set_reference
+        result << op.get(value)
       end
 
       # fetch all optional ones
@@ -413,7 +504,9 @@ module Vips
         arg_name = key.to_s
 
         if optional_output.has_key? arg_name
-          optional_results[arg_name] = op.get arg_name
+          value = op.get arg_name
+          flat_find value, &set_reference
+          optional_results[arg_name] = value
         end
       end
 
@@ -425,11 +518,11 @@ module Vips
         result = nil
       end
 
-      GLib::logger.debug("Vips::Operation.call") { "result = #{result}" }
+      GLib.logger.debug("Vips::Operation.call") { "result = #{result}" }
 
-      Vips::vips_object_unref_outputs op
+      Vips.vips_object_unref_outputs op
 
-      return result
+      result
     end
   end
 end

data/lib/vips/region.rb

@@ -4,12 +4,12 @@
 # Author::    John Cupitt  (mailto:jcupitt@gmail.com)
 # License::   MIT
 
-require 'ffi'
+require "ffi"
 
 module Vips
   attach_function :vips_region_new, [:pointer], :pointer
 
-  if Vips::at_least_libvips?(8, 8)
+  if Vips.at_least_libvips?(8, 8)
     attach_function :vips_region_fetch, [:pointer, :int, :int, :int, :int, SizeStruct.ptr], :pointer
     attach_function :vips_region_width, [:pointer], :int
     attach_function :vips_region_height, [:pointer], :int
@@ -44,24 +44,24 @@ module Vips
     end
 
     def initialize(name)
-      ptr = Vips::vips_region_new name
+      ptr = Vips.vips_region_new name
       raise Vips::Error if ptr.null?
 
       super ptr
     end
 
     def width
-      Vips::vips_region_width self
+      Vips.vips_region_width self
     end
 
     def height
-      Vips::vips_region_height self
+      Vips.vips_region_height self
     end
 
     # Fetch a region filled with pixel data.
     def fetch(left, top, width, height)
       len = Vips::SizeStruct.new
-      ptr = Vips::vips_region_fetch self, left, top, width, height, len
+      ptr = Vips.vips_region_fetch self, left, top, width, height, len
       raise Vips::Error if ptr.null?
 
       # wrap up as an autopointer

data/lib/vips/source.rb

@@ -4,10 +4,10 @@
 # Author::    John Cupitt  (mailto:jcupitt@gmail.com)
 # License::   MIT
 
-require 'ffi'
+require "ffi"
 
 module Vips
-  if Vips::at_least_libvips?(8, 9)
+  if Vips.at_least_libvips?(8, 9)
     attach_function :vips_source_new_from_descriptor, [:int], :pointer
     attach_function :vips_source_new_from_file, [:pointer], :pointer
     attach_function :vips_source_new_from_memory, [:pointer, :size_t], :pointer
@@ -42,26 +42,26 @@ module Vips
     #
     # Pass sources to {Image.new_from_source} to load images from
     # them.
-    # 
+    #
     # @param descriptor [Integer] the file descriptor
     # @return [Source] the new Vips::Source
     def self.new_from_descriptor(descriptor)
-      ptr = Vips::vips_source_new_from_descriptor descriptor
+      ptr = Vips.vips_source_new_from_descriptor descriptor
       raise Vips::Error if ptr.null?
 
       Vips::Source.new ptr
     end
 
-    # Create a new source from a file name. 
+    # Create a new source from a file name.
     #
     # Pass sources to {Image.new_from_source} to load images from
     # them.
-    # 
+    #
     # @param filename [String] the name of the file
     # @return [Source] the new Vips::Source
     def self.new_from_file(filename)
       raise Vips::Error, "filename is nil" if filename.nil?
-      ptr = Vips::vips_source_new_from_file filename
+      ptr = Vips.vips_source_new_from_file filename
       raise Vips::Error if ptr.null?
 
       Vips::Source.new ptr
@@ -72,18 +72,17 @@ module Vips
     #
     # Pass sources to {Image.new_from_source} to load images from
     # them.
-    # 
-    # @param data [String] memory area 
+    #
+    # @param data [String] memory area
     # @return [Source] the new Vips::Source
     def self.new_from_memory(data)
-      ptr = Vips::vips_source_new_from_memory data, data.bytesize
+      ptr = Vips.vips_source_new_from_memory data, data.bytesize
       raise Vips::Error if ptr.null?
 
-      # FIXME do we need to keep a ref to the underlying memory area? what 
+      # FIXME do we need to keep a ref to the underlying memory area? what
       # about Image.new_from_buffer? Does that need a secret ref too?
 
       Vips::Source.new ptr
     end
-
   end
 end

data/lib/vips/sourcecustom.rb

@@ -4,14 +4,14 @@
 # Author::    John Cupitt  (mailto:jcupitt@gmail.com)
 # License::   MIT
 
-require 'ffi'
+require "ffi"
 
 module Vips
-  if Vips::at_least_libvips?(8, 9)
+  if Vips.at_least_libvips?(8, 9)
     attach_function :vips_source_custom_new, [], :pointer
   end
 
-  # A source you can attach action signal handlers to to implement 
+  # A source you can attach action signal handlers to to implement
   # custom input types.
   #
   # For example:
@@ -23,7 +23,7 @@ module Vips
   # image = Vips::Image.new_from_source source
   # ```
   #
-  # (just an example -- of course in practice you'd use {Source#new_from_file} 
+  # (just an example -- of course in practice you'd use {Source#new_from_file}
   # to read from a named file)
   class SourceCustom < Vips::Source
     module SourceCustomLayout
@@ -44,7 +44,7 @@ module Vips
     end
 
     def initialize
-      pointer = Vips::vips_source_custom_new
+      pointer = Vips.vips_source_custom_new
       raise Vips::Error if pointer.null?
 
       super pointer
@@ -60,7 +60,7 @@ module Vips
     def on_read &block
       signal_connect "read" do |buf, len|
         chunk = block.call len
-        return 0 if chunk == nil
+        return 0 if chunk.nil?
         bytes_read = chunk.bytesize
         buf.put_bytes(0, chunk, 0, bytes_read)
         chunk.clear
@@ -70,7 +70,7 @@ module Vips
     end
 
     # The block is executed to seek the source. The interface is exactly as
-    # IO::seek, ie. it should take an offset and whence, and return the 
+    # IO::seek, ie. it should take an offset and whence, and return the
     # new read position.
     #
     # This handler is optional -- if you do not attach a seek handler,
@@ -85,6 +85,5 @@ module Vips
         block.call offset, whence
       end
     end
-
   end
 end