vips 8.8.3 → 8.11.3

data/lib/vips/region.rb

@@ -0,0 +1,73 @@
+# This module provides an interface to the top level bits of libvips
+# via ruby-ffi.
+#
+# Author::    John Cupitt  (mailto:jcupitt@gmail.com)
+# License::   MIT
+
+require 'ffi'
+
+module Vips
+  attach_function :vips_region_new, [:pointer], :pointer
+
+  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
+  end
+
+  # A region on an image. Create one, then use `fetch` to quickly get a region
+  # of pixels.
+  #
+  # For example:
+  #
+  #  ```ruby
+  #  region = Vips::Region.new(image)
+  #  pixels = region.fetch(10, 10, 100, 100)
+  #  ```
+  class Region < Vips::Object
+    # The layout of the VipsRegion struct.
+    module RegionLayout
+      def self.included(base)
+        base.class_eval do
+          layout :parent, Vips::Object::Struct
+          # rest opaque
+        end
+      end
+    end
+
+    class Struct < Vips::Object::Struct
+      include RegionLayout
+    end
+
+    class ManagedStruct < Vips::Object::ManagedStruct
+      include RegionLayout
+    end
+
+    def initialize(name)
+      ptr = Vips::vips_region_new name
+      raise Vips::Error if ptr.null?
+
+      super ptr
+    end
+
+    def width
+      Vips::vips_region_width self
+    end
+
+    def height
+      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
+      raise Vips::Error if ptr.null?
+
+      # wrap up as an autopointer
+      ptr = FFI::AutoPointer.new(ptr, GLib::G_FREE)
+
+      ptr.get_bytes 0, len[:value]
+    end
+  end
+end

data/lib/vips/source.rb

@@ -0,0 +1,89 @@
+# This module provides an interface to the top level bits of libvips
+# via ruby-ffi.
+#
+# Author::    John Cupitt  (mailto:jcupitt@gmail.com)
+# License::   MIT
+
+require 'ffi'
+
+module Vips
+  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
+  end
+
+  # A source. For example:
+  #
+  # ```ruby
+  # source = Vips::Source.new_from_file("k2.jpg")
+  # image = Vips::Image.new_from_source(source)
+  # ```
+  class Source < Vips::Connection
+    module SourceLayout
+      def self.included(base)
+        base.class_eval do
+          layout :parent, Vips::Connection::Struct
+          # rest opaque
+        end
+      end
+    end
+
+    class Struct < Vips::Connection::Struct
+      include SourceLayout
+    end
+
+    class ManagedStruct < Vips::Connection::ManagedStruct
+      include SourceLayout
+    end
+
+    # Create a new source from a file descriptor. File descriptors are
+    # small integers, for example 0 is stdin.
+    #
+    # 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
+      raise Vips::Error if ptr.null?
+
+      Vips::Source.new ptr
+    end
+
+    # 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
+      raise Vips::Error if ptr.null?
+
+      Vips::Source.new ptr
+    end
+
+    # Create a new source from an area of memory. Memory areas can be
+    # strings, arrays and so forth -- anything that supports bytesize.
+    #
+    # Pass sources to {Image.new_from_source} to load images from
+    # them.
+    # 
+    # @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
+      raise Vips::Error if ptr.null?
+
+      # 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

@@ -0,0 +1,90 @@
+# This module provides an interface to the top level bits of libvips
+# via ruby-ffi.
+#
+# Author::    John Cupitt  (mailto:jcupitt@gmail.com)
+# License::   MIT
+
+require 'ffi'
+
+module Vips
+  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 
+  # custom input types.
+  #
+  # For example:
+  #
+  # ```ruby
+  # file = File.open "some/file/name", "rb"
+  # source = Vips::SourceCustom.new
+  # source.on_read { |length| file.read length }
+  # image = Vips::Image.new_from_source source
+  # ```
+  #
+  # (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
+      def self.included(base)
+        base.class_eval do
+          layout :parent, Vips::Source::Struct
+          # rest opaque
+        end
+      end
+    end
+
+    class Struct < Vips::Source::Struct
+      include SourceCustomLayout
+    end
+
+    class ManagedStruct < Vips::Source::ManagedStruct
+      include SourceCustomLayout
+    end
+
+    def initialize
+      pointer = Vips::vips_source_custom_new
+      raise Vips::Error if pointer.null?
+
+      super pointer
+    end
+
+    # The block is executed to read data from the source. The interface is
+    # exactly as IO::read, ie. it takes a maximum number of bytes to read and
+    # returns a string of bytes from the source, or nil if the source is already
+    # at end of file.
+    #
+    # @yieldparam length [Integer] Read and return up to this many bytes
+    # @yieldreturn [String] Up to length bytes of data, or nil for EOF
+    def on_read &block
+      signal_connect "read" do |buf, len|
+        chunk = block.call len
+        return 0 if chunk == nil
+        bytes_read = chunk.bytesize
+        buf.put_bytes(0, chunk, 0, bytes_read)
+        chunk.clear
+
+        bytes_read
+      end
+    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 
+    # new read position.
+    #
+    # This handler is optional -- if you do not attach a seek handler,
+    # {Source} will treat your source like an unseekable pipe object and
+    # do extra caching.
+    #
+    # @yieldparam offset [Integer] Seek offset
+    # @yieldparam whence [Integer] Seek whence
+    # @yieldreturn [Integer] the new read position, or -1 on error
+    def on_seek &block
+      signal_connect "seek" do |offset, whence|
+        block.call offset, whence
+      end
+    end
+
+  end
+end

data/lib/vips/target.rb

@@ -0,0 +1,87 @@
+# This module provides an interface to the top level bits of libvips
+# via ruby-ffi.
+#
+# Author::    John Cupitt  (mailto:jcupitt@gmail.com)
+# License::   MIT
+
+require 'ffi'
+
+module Vips
+  if Vips::at_least_libvips?(8, 9)
+    attach_function :vips_target_new_to_descriptor, [:int], :pointer
+    attach_function :vips_target_new_to_file, [:string], :pointer
+    attach_function :vips_target_new_to_memory, [], :pointer
+  end
+
+  # A target. For example:
+  #
+  # ```ruby
+  # target = Vips::Target.new_to_file('k2.jpg')
+  # image.write_to_target(target, '.jpg')
+  # ```
+  class Target < Vips::Connection
+    # The layout of the VipsRegion struct.
+    module TargetLayout
+      def self.included(base)
+        base.class_eval do
+          layout :parent, Vips::Connection::Struct
+          # rest opaque
+        end
+      end
+    end
+
+    class Struct < Vips::Connection::Struct
+      include TargetLayout
+    end
+
+    class ManagedStruct < Vips::Connection::ManagedStruct
+      include TargetLayout
+    end
+
+    # Create a new target to a file descriptor. File descriptors are
+    # small integers, for example 1 is stdout.
+    #
+    # Pass targets to {Image#write_to_target} to write images to
+    # them.
+    # 
+    # @param descriptor [Integer] the file descriptor
+    # @return [Target] the new Vips::Target
+    def self.new_to_descriptor(descriptor)
+      ptr = Vips::vips_target_new_to_descriptor descriptor
+      raise Vips::Error if ptr.null?
+
+      Vips::Target.new ptr
+    end
+
+    # Create a new target to a file name. 
+    #
+    # Pass targets to {Image#write_to_target} to write images to
+    # them.
+    # 
+    # @param filename [String] the name of the file
+    # @return [Target] the new Vips::Target
+    def self.new_to_file(filename)
+      raise Vips::Error, 'filename is nil' if filename.nil?
+      ptr = Vips::vips_target_new_to_file filename
+      raise Vips::Error if ptr.null?
+
+      Vips::Target.new ptr
+    end
+
+    # Create a new target to an area of memory. 
+    #
+    # Pass targets to {Image#write_to_target} to write images to
+    # them.
+    #
+    # Once the image has been written, use {Object#get}`("blob")` to read out 
+    # the data.
+    # 
+    # @return [Target] the new Vips::Target
+    def self.new_to_memory
+      ptr = Vips::vips_target_new_to_memory 
+
+      Vips::Target.new ptr
+    end
+
+  end
+end

data/lib/vips/targetcustom.rb

@@ -0,0 +1,78 @@
+# This module provides an interface to the top level bits of libvips
+# via ruby-ffi.
+#
+# Author::    John Cupitt  (mailto:jcupitt@gmail.com)
+# License::   MIT
+
+require 'ffi'
+
+module Vips
+  if Vips::at_least_libvips?(8, 9)
+    attach_function :vips_target_custom_new, [], :pointer
+  end
+
+  # A target you can attach action signal handlers to to implememt 
+  # custom output types.
+  #
+  # For example:
+  #
+  # ```ruby
+  # file = File.open "some/file/name", "wb"
+  # target = Vips::TargetCustom.new
+  # target.on_write { |bytes| file.write bytes }
+  # image.write_to_target target, ".png"
+  # ```
+  #
+  # (just an example -- of course in practice you'd use {Target#new_to_file} 
+  # to write to a named file)
+  class TargetCustom < Vips::Target
+    module TargetCustomLayout
+      def self.included(base)
+        base.class_eval do
+          layout :parent, Vips::Target::Struct
+          # rest opaque
+        end
+      end
+    end
+
+    class Struct < Vips::Target::Struct
+      include TargetCustomLayout
+    end
+
+    class ManagedStruct < Vips::Target::ManagedStruct
+      include TargetCustomLayout
+    end
+
+    def initialize
+      pointer = Vips::vips_target_custom_new
+      raise Vips::Error if pointer.null?
+
+      super pointer
+    end
+
+    # The block is executed to write data to the source. The interface is
+    # exactly as IO::write, ie. it should write the string and return the 
+    # number of bytes written.
+    #
+    # @yieldparam bytes [String] Write these bytes to the file 
+    # @yieldreturn [Integer] The number of bytes written, or -1 on error
+    def on_write &block
+      signal_connect "write" do |p, len|
+        chunk = p.get_bytes(0, len)
+        bytes_written = block.call chunk
+        chunk.clear
+
+        bytes_written
+      end
+    end
+
+    # The block is executed at the end of write. It should do any necessary
+    # finishing action, such as closing a file.
+    def on_finish &block
+      signal_connect "finish" do 
+        block.call()
+      end
+    end
+
+  end
+end

data/lib/vips/version.rb

@@ -1,4 +1,4 @@
 
 module Vips
-	VERSION = "8.8.3"
+	VERSION = "8.11.3"
 end

data/lib/vips.rb

@@ -10,6 +10,29 @@ require 'logger'
 # This module uses FFI to make a simple layer over the glib and gobject
 # libraries.
 
+# Generate a library name for ffi.
+#
+# Platform notes:
+# linux:
+#   Some distros allow "libvips.so", but only if the -dev headers have been
+#   installed. To work everywhere, you must include the ABI number.
+#   Confusingly, the file extension is not at the end. ffi adds the "lib"
+#   prefix.
+# mac:
+#   As linux, but the extension is at the end and is added by ffi.
+# windows:
+#   The ABI number must be included, but with a hyphen. ffi does not add a
+#   "lib" prefix or a ".dll" suffix.
+def library_name(name, abi_number)
+  if FFI::Platform.windows?
+    "lib#{name}-#{abi_number}.dll"
+  elsif FFI::Platform.mac?
+    "#{name}.#{abi_number}"
+  else
+    "#{name}.so.#{abi_number}"
+  end
+end
+
 module GLib
   class << self
     attr_accessor :logger
@@ -19,13 +42,7 @@ module GLib
 
   extend FFI::Library
 
-  if FFI::Platform.windows?
-    glib_libname = 'libglib-2.0-0.dll'
-  else
-    glib_libname = 'glib-2.0'
-  end
-
-  ffi_lib glib_libname
+  ffi_lib library_name('glib-2.0', 0)
 
   attach_function :g_malloc, [:size_t], :pointer
 
@@ -117,13 +134,7 @@ end
 module GObject
   extend FFI::Library
 
-  if FFI::Platform.windows?
-    gobject_libname = 'libgobject-2.0-0.dll'
-  else
-    gobject_libname = 'gobject-2.0'
-  end
-
-  ffi_lib gobject_libname
+  ffi_lib library_name('gobject-2.0', 0)
 
   # we can't just use ulong, windows has different int sizing rules
   if FFI::Platform::ADDRESS_SIZE == 64
@@ -155,7 +166,7 @@ require 'vips/gobject'
 require 'vips/gvalue'
 
 # This module provides a binding for the [libvips image processing
-# library](https://jcupitt.github.io/libvips/).
+# library](https://libvips.github.io/libvips/).
 #
 # # Example
 #
@@ -201,6 +212,9 @@ require 'vips/gvalue'
 # memory buffers, create images that wrap C-style memory arrays, or make images
 # from constants.
 #
+# Use {Source} and {Image.new_from_source} to load images from any data
+# source, for example URIs.
+#
 # The next line:
 #
 # ```ruby
@@ -242,6 +256,9 @@ require 'vips/gvalue'
 # suffix. You can also write formatted images to memory buffers, or dump
 # image data to a raw memory array.
 #
+# Use {Target} and {Image#write_to_target} to write formatted images to 
+# any data sink, for example URIs.
+#
 # # How it works
 #
 # The binding uses [ruby-ffi](https://github.com/ffi/ffi) to open the libvips
@@ -393,12 +410,12 @@ require 'vips/gvalue'
 # # Automatic YARD documentation
 #
 # The bulk of these API docs are generated automatically by
-# {Vips::generate_yard}. It examines
+# {Vips::Yard::generate}. It examines
 # libvips and writes a summary of each operation and the arguments and options
 # that that operation expects.
 #
 # Use the [C API
-# docs](https://jcupitt.github.io/libvips/API/current)
+# docs](https://libvips.github.io/libvips/API/current)
 # for more detail.
 #
 # # Enums
@@ -423,6 +440,55 @@ require 'vips/gvalue'
 # If you want to avoid the copies, you'll need to call drawing operations
 # yourself.
 #
+# # Progress
+#
+# You can attach signal handlers to images to watch computation progress. For
+# example:
+#
+# ```ruby
+# image = Vips::Image.black 1, 100000
+# image.set_progress true
+# 
+# def progress_to_s(name, progress)
+#   puts "#{name}:"
+#   puts "    run = #{progress[:run]}"
+#   puts "    eta = #{progress[:eta]}"
+#   puts "    tpels = #{progress[:tpels]}"
+#   puts "    npels = #{progress[:npels]}"
+#   puts "    percent = #{progress[:percent]}"
+# end
+# 
+# image.signal_connect :preeval do |progress|
+#   progress_to_s("preeval", progress)
+# end
+# 
+# image.signal_connect :eval do |progress|
+#   progress_to_s("eval", progress)
+#   image.set_kill(true) if progress[:percent] > 50
+# end
+# 
+# image.signal_connect :posteval do |progress|
+#   progress_to_s("posteval", progress)
+# end
+# 
+# image.avg
+# ```
+# 
+# The `:eval` signal will fire for every tile that is processed. You can stop
+# progress with {Image#set_kill} and processing will end with an exception.
+#
+# User streams
+#
+# You can make your own input and output stream objects with {SourceCustom} and
+# {TargetCustom}. For example:
+#
+# ```ruby
+# file = File.open "some/file", "rb"
+# source = Vips::SourceCustom.new
+# source.on_read { |length| file.read length }
+# image = Vips::Image.new_from_source source, "", access: "sequential"
+# ```
+#
 # # Overloads
 #
 # The wrapper defines the usual set of arithmetic, boolean and relational
@@ -462,7 +528,7 @@ module Vips
   if FFI::Platform.windows?
     vips_libname = 'libvips-42.dll'
   else
-    vips_libname = File.expand_path(FFI::map_library_name('vips'), __dir__)
+    vips_libname = File.expand_path(FFI.map_library_name('vips'), __dir__)
   end
 
   ffi_lib vips_libname
@@ -609,7 +675,7 @@ module Vips
   LIBRARY_VERSION = Vips::version_string
 
   # libvips has this arbitrary number as a sanity-check upper bound on image
-  # size. It's sometimes useful for know whan calculating image ratios.
+  # size. It's sometimes useful to know when calculating scale factors.
   MAX_COORD = 10000000
 end
 
@@ -617,4 +683,10 @@ require 'vips/object'
 require 'vips/operation'
 require 'vips/image'
 require 'vips/interpolate'
+require 'vips/region'
 require 'vips/version'
+require 'vips/connection'
+require 'vips/source'
+require 'vips/sourcecustom'
+require 'vips/target'
+require 'vips/targetcustom'