vips.rb in vips-8.9.1

- old
+ new

@@ -8,27 +8,44 @@
 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
   end
   @logger = Logger.new(STDOUT)
   @logger.level = Logger::WARN
 
   extend FFI::Library
 
-  if FFI::Platform.windows?
-    glib_libname = 'libglib-2.0-0.dll'
-  else
-    glib_libname = 'glib-2.0'
-  end
+  ffi_lib library_name('glib-2.0', 0)
 
-  ffi_lib glib_libname
-
   attach_function :g_malloc, [:size_t], :pointer
 
   # save the FFI::Function that attach will return ... we can use it directly
   # as a param for callbacks
   G_FREE = attach_function :g_free, [:pointer], :void
@@ -115,18 +132,12 @@
 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 library_name('gobject-2.0', 0)
 
-  ffi_lib gobject_libname
-
   # 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
@@ -153,11 +164,11 @@
 
 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
 #
 # ```ruby
 # require 'vips'
@@ -199,10 +210,13 @@
 #
 # You can also load formatted images from
 # 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
 # im *= [1, 2, 1]
 # ```
@@ -240,10 +254,13 @@
 # {Image#write_to_file} writes an image back to the filesystem. It can
 # write any format supported by vips: the file type is set from the filename
 # 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
 # shared library. When you call a method on the image class, it uses libvips
 # introspection system (based on GObject) to search the
@@ -391,16 +408,16 @@
 # exception. You can catch it in the usual way.
 #
 # # 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
 #
 # The libvips enums, such as `VipsBandFormat` appear in ruby-vips as Symbols
@@ -421,10 +438,59 @@
 # where possible, so you won't have 100 copies in memory.
 #
 # 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
 # overloads on image. You can mix images, constants and lists of constants
 # (almost) freely. For example, you can write:
@@ -460,11 +526,11 @@
   extend FFI::Library
 
   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
 
   LOG_DOMAIN = "VIPS"
@@ -607,14 +673,20 @@
   end
 
   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
 
 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'