ruby-vips 2.1.0 → 2.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b632e0e44fa32da791e46806757e9b6a1a9901d92e2de9b02e16682bc3f3e6b2
-  data.tar.gz: 5d3841b9a656d13003b1b2668c05ab89cf5b65c76a52dad070a67b9a6856fe60
+  metadata.gz: ff74e4e7a8b781e9fd56602fddc00adaa0355276532821a953bac3175e649534
+  data.tar.gz: 199957dacc1c47208a5d8a379080b76676fe3f98ba684a76fdbe5e08370d535b
 SHA512:
-  metadata.gz: 11c11a729818aa279cf5a157cda6e810174da9089b9ae3a0e92b3c7e6080362dfca5a970b07f3881aa7f31e5aa4acf3cd1a9a05a2e3ef09dc86d7464fe8987fe
-  data.tar.gz: 41bae93d0c491699e0042acfe687bc86766af576c9ffe57da1c20a26de548e08c73c0d7685855a155630ed5d47a3a2e2e60f982df48df2a59d4a9f4bd6ccfd34
+  metadata.gz: 9d585d3440f75759e1c07cefd6d43371db62706e0c2e9ada3512f661870f7f4c410d6dbeed138c45e16438112cc8179bae2d4477c318ac6fcf9e31487822cb63
+  data.tar.gz: a62254d063cd35b521e74a86377d3e83d2b2345a10186e044b2e91992bc6ff49611d6bde916cd8c530d0b2ba4da7ba4a23ca10c922be99463ab71371538cf1cf

data/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## master
 
+## Version 2.1.4 (2021-10-28)
+
+* `write_to_buffer` tries to use the new target API, then falls back to the old 
+  buffer system [jcupitt]
+* don't generate yard docs for deprecated args [jcupitt]
+* add hyperbolic trig functions [jcupitt]
+
+## Version 2.1.3 (2021-8-23)
+
+* fix a gtype size error on win64 [danini-the-panini]
+
+## Version 2.1.2 (2021-5-3)
+
+* allow `FFI::Pointer` as an argument to `new_from_memory` etc. [sled]
+
+## Version 2.1.1 (2021-5-3)
+
+* fix "mutate" with libvips 8.9 [jcupitt]
+* update autodocs for libvips 8.11 [jcupitt]
+
 ## Version 2.1.0 (2021-3-8)
 
 * add "mutate" system [jcupitt]

data/README.md

@@ -6,12 +6,13 @@
 This gem is a Ruby binding for the [libvips image processing
 library](https://libvips.github.io/libvips).
 
-Programs that use `ruby-vips` don't manipulate images directly, instead
-they create pipelines of image processing operations building on a source
-image. When the end of the pipe is connected to a destination, the whole
-pipeline executes at once, streaming the image in parallel from source to
-destination a section at a time.  Because `ruby-vips` is parallel, it's quick,
-and because it doesn't need to keep entire images in memory, it's light.
+libvips is a [demand-driven, horizontally
+threaded](https://github.com/libvips/libvips/wiki/Why-is-libvips-quick)
+image processing library. Compared to similar
+libraries, [libvips runs quickly and uses little
+memory](https://github.com/libvips/libvips/wiki/Speed-and-memory-use).
+libvips is licensed under the [LGPL
+2.1+](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html).
 
 ## Requirements
 
@@ -25,7 +26,7 @@ and because it doesn't need to keep entire images in memory, it's light.
 
 ## Install
 
-It's just:
+[Install libvips](https://libvips.github.io/libvips/install.html), then:
 
 ```
 $ gem install ruby-vips
@@ -40,7 +41,7 @@ gem "ruby-vips"
 On Windows, you'll need to set the `RUBY_DLL_PATH` environment variable to 
 point to the libvips bin directory.
 
-# Example
+## Example
 
 ```ruby
 require "vips"
@@ -67,19 +68,24 @@ im = im.conv mask, precision: :integer
 im.write_to_file output_filename
 ```
 
-The `Vips` section in the API docs has a [tutorial introduction with
+## Documentation
+
+There are [full API docs for ruby-vips on
+rubydoc](https://www.rubydoc.info/gems/ruby-vips). This sometimes has issues
+updating, so we have a [copy on the gh-pages for this site as
+well](http://libvips.github.io/ruby-vips), which
+should always work.
+
+See the `Vips` section in the docs for a [tutorial introduction with
 examples](https://www.rubydoc.info/gems/ruby-vips/Vips).
 
-ruby-vips has [API
- documentation](http://www.rubydoc.info/gems/ruby-vips). The [libvips
- reference manual](https://libvips.github.io/libvips/API/current/) has a
- complete explanation of every method.
+The [libvips reference manual](https://libvips.github.io/libvips/API/current/)
+has a complete explanation of every method.
 
-The 
-[`example/`](https://github.com/libvips/ruby-vips/tree/master/example)
+The [`example/`](https://github.com/libvips/ruby-vips/tree/master/example)
 directory has some simple example programs.
 
-# Benchmarks
+## Benchmarks
 
 The benchmark at [vips-benchmarks](https://github.com/jcupitt/vips-benchmarks)
 loads a large image, crops, shrinks, sharpens and saves again, and repeats

data/TODO

@@ -37,9 +37,8 @@
 
 - Push new gem to rubygems, tag repository with version.
 
-	gem2.5 signin --otp 111111 / enter username and passwd
+	gem signin --otp 111111 
 	bundle exec rake release
 
-  There's an invisible prompt for the authenticator code. Enter eg. 123456, 
-  press return and the upload should work.
+  The otp is from authy / google authenticator / etc. 
 

data/VERSION

@@ -1 +1 @@
-2.1.0
+2.1.4

data/example/inheritance_with_refcount.rb

@@ -132,8 +132,12 @@ module GLib
     end
   end
 
-  # :gtype will usually be 64-bit, but will be 32-bit on 32-bit Windows
-  typedef :ulong, :GType
+  # we can't just use ulong, windows has different int sizing rules
+  if FFI::Platform::ADDRESS_SIZE == 64
+    typedef :uint64, :GType
+  else
+    typedef :uint32, :GType
+  end
 end
 
 module Vips
@@ -144,7 +148,11 @@ module Vips
   GLib.set_log_domain(LOG_DOMAIN)
 
   # need to repeat this
-  typedef :ulong, :GType
+  if FFI::Platform::ADDRESS_SIZE == 64
+    typedef :uint64, :GType
+  else
+    typedef :uint32, :GType
+  end
 
   attach_function :vips_init, [:string], :int
   attach_function :vips_shutdown, [], :void

data/lib/vips/image.rb

@@ -78,6 +78,11 @@ module Vips
   class Image < Vips::Object
     alias_method :parent_get_typeof, :get_typeof
 
+    # FFI sets a pointer's size to this magic value if the size of the memory
+    # chunk the pointer points to is unknown to FFI.
+    UNKNOWN_POINTER_SIZE = FFI::Pointer.new(1).size
+    private_constant :UNKNOWN_POINTER_SIZE
+
     private
 
     # the layout of the VipsImage struct
@@ -326,6 +331,24 @@ module Vips
     #   image.width, image.height, image.bands, image.format
     # ```
     #
+    # Creating a new image from a memory pointer:
+    #
+    # ```
+    # ptr = FFI::MemoryPointer.new(:uchar, 10*10)
+    # # => #<FFI::MemoryPointer address=0x00007fc236db31d0 size=100>
+    # x = Vips::Image.new_from_memory(ptr, 10, 10, 1, :uchar)
+    # ```
+    #
+    # Creating a new image from an address only pointer:
+    #
+    # ```
+    # ptr = call_to_external_c_library(w: 10, h: 10)
+    # # => #<FFI::Pointer address=0x00007f9780813a00>
+    # ptr_slice = ptr.slice(0, 10*10)
+    # # => #<FFI::Pointer address=0x00007f9780813a00 size=100>
+    # x = Vips::Image.new_from_memory(ptr_slice, 10, 10, 1, :uchar)
+    # ```
+    #
     # {new_from_memory} keeps a reference to the array of pixels you pass in
     # to try to prevent that memory from being freed by the Ruby GC while it
     # is being used.
@@ -340,13 +363,23 @@ module Vips
     # @param format [Symbol] band format
     # @return [Image] the loaded image
     def self.new_from_memory data, width, height, bands, format
-      size = data.bytesize
-
       # prevent data from being freed with JRuby FFI
       if defined?(JRUBY_VERSION) && !data.is_a?(FFI::Pointer)
         data = ::FFI::MemoryPointer.new(:char, data.bytesize).write_bytes data
       end
 
+      if data.is_a?(FFI::Pointer)
+        # A pointer needs to know about the size of the memory it points to.
+        # If you have an address-only pointer, use the .slice method to wrap
+        # the pointer in a size aware pointer.
+        if data.size == UNKNOWN_POINTER_SIZE
+          raise Vips::Error, "size of memory is unknown"
+        end
+        size = data.size
+      else
+        size = data.bytesize
+      end
+
       format_number = GObject::GValue.from_nick BAND_FORMAT_TYPE, format
       vi = Vips.vips_image_new_from_memory data, size,
         width, height, bands, format_number
@@ -373,7 +406,17 @@ module Vips
     # @return [Image] the loaded image
     def self.new_from_memory_copy data, width, height, bands, format
       format_number = GObject::GValue.from_nick BAND_FORMAT_TYPE, format
-      vi = Vips.vips_image_new_from_memory_copy data, data.bytesize,
+
+      if data.is_a?(FFI::Pointer)
+        if data.size == UNKNOWN_POINTER_SIZE
+          raise Vips::Error, "size of memory is unknown"
+        end
+        size = data.size
+      else
+        size = data.bytesize
+      end
+
+      vi = Vips.vips_image_new_from_memory_copy data, size,
         width, height, bands, format_number
       raise Vips::Error if vi.null?
       new(vi)
@@ -506,7 +549,7 @@ module Vips
       pixel = (Vips::Image.black(1, 1) + value).cast(format)
       image = pixel.embed 0, 0, width, height, extend: :copy
       image.copy interpretation: interpretation, xres: xres, yres: yres,
-                 xoffset: xoffset, yoffset: yoffset
+        xoffset: xoffset, yoffset: yoffset
     end
 
     # Write this image to a file. Save options may be encoded in the
@@ -580,11 +623,27 @@ module Vips
       raise Vips::Error, "filename is nil" if format_string.nil?
       filename = Vips.p2str(Vips.vips_filename_get_filename(format_string))
       option_string = Vips.p2str(Vips.vips_filename_get_options(format_string))
-      saver = Vips.vips_foreign_find_save_buffer filename
-      raise Vips::Error if saver.nil?
 
-      buffer = Vips::Operation.call saver, [self], opts, option_string
-      raise Vips::Error if buffer.nil?
+      # try to save with the new target API first, only fall back to the old
+      # buffer API if there's no target save for this filetype
+      saver = nil
+      if Vips.at_least_libvips?(8, 9)
+        Vips.vips_error_freeze
+        saver = Vips.vips_foreign_find_save_target filename
+        Vips.vips_error_thaw
+      end
+
+      if !saver.nil?
+        target = Vips::Target.new_to_memory
+        Vips::Operation.call saver, [self, target], opts, option_string
+        buffer = target.get("blob")
+      else
+        saver = Vips.vips_foreign_find_save_buffer filename
+        raise Vips::Error if saver.nil?
+
+        buffer = Vips::Operation.call saver, [self], opts, option_string
+        raise Vips::Error if buffer.nil?
+      end
 
       write_gc
 
@@ -1129,14 +1188,10 @@ module Vips
       end
     end
 
-    # Convert to an Array. This will be slow for large images.
+    # Convert to an Enumerator. Similar to `#to_a` but lazier.
     #
-    # @return [Array] array of Fixnum
-    def to_a
-      # we render the image to a big string, then unpack
-      # as a Ruby array of the correct type
-      memory = write_to_memory
-
+    # @return [Enumerator] Enumerator of Enumerators of Arrays of Numerics
+    def to_enum
       # make the template for unpack
       template = {
         char: "c",
@@ -1151,14 +1206,22 @@ module Vips
         dpcomplex: "d"
       }[format] + "*"
 
-      # and unpack into something like [1, 2, 3, 4 ..]
-      array = memory.unpack(template)
+      # we render the image to a big string, then unpack into
+      # one-dimensional array as a Ruby array of the correct type
+      array = write_to_memory.unpack template
 
-      # gather band elements together
-      pixel_array = array.each_slice(bands).to_a
+      # gather bands of a pixel together
+      pixel_array = array.each_slice bands
 
-      # build rows
-      pixel_array.each_slice(width).to_a
+      # gather pixels of a row together
+      pixel_array.each_slice width
+    end
+
+    # Convert to an Array. This will be slow for large images.
+    #
+    # @return [Array] Array of Arrays of Arrays of Numerics
+    def to_a
+      to_enum.to_a
     end
 
     # Return the largest integral value not greater than the argument.
@@ -1387,6 +1450,48 @@ module Vips
       math :atan
     end
 
+    # Return the hyperbolic sine of an image in radians.
+    #
+    # @return [Image] sine of each pixel
+    def sinh
+      math :sinh
+    end
+
+    # Return the hyperbolic cosine of an image in radians.
+    #
+    # @return [Image] cosine of each pixel
+    def cosh
+      math :cosh
+    end
+
+    # Return the hyperbolic tangent of an image in radians.
+    #
+    # @return [Image] tangent of each pixel
+    def tanh
+      math :tanh
+    end
+
+    # Return the inverse hyperbolic sine of an image in radians.
+    #
+    # @return [Image] inverse sine of each pixel
+    def asinh
+      math :asinh
+    end
+
+    # Return the inverse hyperbolic cosine of an image in radians.
+    #
+    # @return [Image] inverse cosine of each pixel
+    def acosh
+      math :acosh
+    end
+
+    # Return the inverse hyperbolic tangent of an image in radians.
+    #
+    # @return [Image] inverse tangent of each pixel
+    def atanh
+      math :atanh
+    end
+
     # Return the natural log of an image.
     #
     # @return [Image] natural log of each pixel
@@ -1569,8 +1674,8 @@ module Vips
 
       method_args = introspect.method_args
       required_output = introspect.required_output
-      optional_input = introspect.optional_input
-      optional_output = introspect.optional_output
+      optional_input = introspect.doc_optional_input
+      optional_output = introspect.doc_optional_output
 
       print "# @!method "
       print "self." unless introspect.member_x
@@ -1593,17 +1698,18 @@ module Vips
       optional_input.each do |arg_name, details|
         yard_name = details[:yard_name]
         gtype = details[:gtype]
+        rtype = gtype_to_ruby gtype
         blurb = details[:blurb]
 
-        puts "#   @option opts [#{gtype_to_ruby(gtype)}] :#{yard_name} #{blurb}"
+        puts "#   @option opts [#{rtype}] :#{yard_name} #{blurb}"
       end
       optional_output.each do |arg_name, details|
         yard_name = details[:yard_name]
         gtype = details[:gtype]
+        rtype = gtype_to_ruby gtype
         blurb = details[:blurb]
 
-        print "#   @option opts [#{gtype_to_ruby(gtype)}] :#{yard_name}"
-        puts " Output #{blurb}"
+        puts "#   @option opts [#{rtype}] :#{yard_name} Output #{blurb}"
       end
 
       print "#   @return ["