# 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 "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

  ffi_lib library_name("glib-2.0", 0)

  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

  callback :g_log_func, [:string, :int, :string, :pointer], :void
  attach_function :g_log_set_handler,
    [:string, :int, :g_log_func, :pointer], :int
  attach_function :g_log_remove_handler, [:string, :int], :void

  # log flags
  LOG_FLAG_RECURSION = 1 << 0
  LOG_FLAG_FATAL = 1 << 1

  # GLib log levels
  LOG_LEVEL_ERROR = 1 << 2 # always fatal
  LOG_LEVEL_CRITICAL = 1 << 3
  LOG_LEVEL_WARNING = 1 << 4
  LOG_LEVEL_MESSAGE = 1 << 5
  LOG_LEVEL_INFO = 1 << 6
  LOG_LEVEL_DEBUG = 1 << 7

  # map glib levels to Logger::Severity
  GLIB_TO_SEVERITY = {
    LOG_LEVEL_ERROR => Logger::ERROR,
    LOG_LEVEL_CRITICAL => Logger::FATAL,
    LOG_LEVEL_WARNING => Logger::WARN,
    LOG_LEVEL_MESSAGE => Logger::UNKNOWN,
    LOG_LEVEL_INFO => Logger::INFO,
    LOG_LEVEL_DEBUG => Logger::DEBUG
  }
  GLIB_TO_SEVERITY.default = Logger::UNKNOWN

  # nil being the default
  @glib_log_domain = nil
  @glib_log_handler_id = 0

  # module-level, so it's not GCd away
  LOG_HANDLER = proc { |domain, level, message, _user_data|
    @logger.log(GLIB_TO_SEVERITY[level], message, domain)
  }

  def self.remove_log_handler
    if @glib_log_handler_id != 0 && @glib_log_domain
      g_log_remove_handler @glib_log_domain, @glib_log_handler_id
      @glib_log_handler_id = nil
    end
  end

  def self.set_log_domain domain
    GLib.remove_log_handler

    @glib_log_domain = domain

    # forward all glib logging output from this domain to a Ruby logger
    if @glib_log_domain
      # disable this feature for now
      #
      # libvips background worker threads can issue warnings, and
      # since the main thread is blocked waiting for libvips to come back
      # from an ffi call, you get a deadlock on the GIL
      #
      # to fix this, we need a way for g_log() calls from libvips workers
      # to be returned via the main thread
      #

      #             @glib_log_handler_id = g_log_set_handler @glib_log_domain,
      #                 LOG_LEVEL_DEBUG |
      #                 LOG_LEVEL_INFO |
      #                 LOG_LEVEL_MESSAGE |
      #                 LOG_LEVEL_WARNING |
      #                 LOG_LEVEL_ERROR |
      #                 LOG_LEVEL_CRITICAL |
      #                 LOG_FLAG_FATAL | LOG_FLAG_RECURSION,
      #                 LOG_HANDLER, nil

      # we must remove any handlers on exit, since libvips may log stuff
      # on shutdown and we don't want LOG_HANDLER to be invoked
      # after Ruby has gone
      at_exit {
        GLib.remove_log_handler
      }
    end
  end
end

module GObject
  extend FFI::Library

  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
    typedef :uint64, :GType
  else
    typedef :uint32, :GType
  end

  attach_function :g_type_init, [], :void
  attach_function :g_type_name, [:GType], :string
  attach_function :g_type_from_name, [:string], :GType
  attach_function :g_type_fundamental, [:GType], :GType

  # glib before 2.36 needed this, does nothing in current glib
  g_type_init

  # look up some common gtypes
  GBOOL_TYPE = g_type_from_name "gboolean"
  GINT_TYPE = g_type_from_name "gint"
  GUINT64_TYPE = g_type_from_name "guint64"
  GDOUBLE_TYPE = g_type_from_name "gdouble"
  GENUM_TYPE = g_type_from_name "GEnum"
  GFLAGS_TYPE = g_type_from_name "GFlags"
  GSTR_TYPE = g_type_from_name "gchararray"
  GOBJECT_TYPE = g_type_from_name "GObject"
end

require "vips/gobject"
require "vips/gvalue"

# This module provides a binding for the [libvips image processing
# library](https://libvips.github.io/libvips/).
#
# # Example
#
# ```ruby
# require 'vips'
#
# if ARGV.length < 2
#     raise "usage: #{$PROGRAM_NAME}: input-file output-file"
# end
#
# im = Vips::Image.new_from_file ARGV[0], access: :sequential
#
# im *= [1, 2, 1]
#
# mask = Vips::Image.new_from_array [
#         [-1, -1, -1],
#         [-1, 16, -1],
#         [-1, -1, -1]
#        ], 8
# im = im.conv mask, precision: :integer
#
# im.write_to_file ARGV[1]
# ```
#
# This example loads a file, boosts the green channel (I'm not sure why),
# sharpens the image, and saves it back to disc again.
#
# Reading this example line by line, we have:
#
# ```ruby
# im = Vips::Image.new_from_file ARGV[0], access: :sequential
# ```
#
# {Image.new_from_file} can load any image file supported by vips. In this
# example, we will be accessing pixels top-to-bottom as we sweep through the
# image reading and writing, so `:sequential` access mode is best for us. The
# default mode is `:random`: this allows for full random access to image pixels,
# but is slower and needs more memory. See {Access}
# for full details
# on the various modes available.
#
# 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]
# ```
#
# Multiplying the image by an array constant uses one array element for each
# image band. This line assumes that the input image has three bands and will
# double the middle band. For RGB images, that's doubling green.
#
# Next we have:
#
# ```ruby
# mask = Vips::Image.new_from_array [
#         [-1, -1, -1],
#         [-1, 16, -1],
#         [-1, -1, -1]
#        ], 8
# im = im.conv mask, precision: :integer
# ```
#
# {Image.new_from_array} creates an image from an array constant. The 8 at
# the end sets the scale: the amount to divide the image by after
# integer convolution.
#
# See the libvips API docs for `vips_conv()` (the operation
# invoked by {Image#conv}) for details on the convolution operator. By default,
# it computes with a float mask, but `:integer` is fine for this case, and is
# much faster.
#
# Finally:
#
# ```ruby
# im.write_to_file ARGV[1]
# ```
#
# {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
# library for an operation of that name, transforms the arguments to a form
# libvips can digest, and runs the operation.
#
# This means ruby-vips always presents the API implemented by the libvips shared
# library. It should update itself as new features are added.
#
# # Automatic wrapping
#
# `ruby-vips` adds a {Image.method_missing} handler to {Image} and uses
# it to look up vips operations. For example, the libvips operation `add`, which
# appears in C as `vips_add()`, appears in Ruby as {Image#add}.
#
# The operation's list of required arguments is searched and the first input
# image is set to the value of `self`. Operations which do not take an input
# image, such as {Image.black}, appear as class methods. The remainder of
# the arguments you supply in the function call are used to set the other
# required input arguments. Any trailing keyword arguments are used to set
# options on the operation.
#
# The result is the required output
# argument if there is only one result, or an array of values if the operation
# produces several results. If the operation has optional output objects, they
# are returned as a final hash.
#
# For example, {Image#min}, the vips operation that searches an image for
# the minimum value, has a large number of optional arguments. You can use it to
# find the minimum value like this:
#
# ```ruby
# min_value = image.min
# ```
#
# You can ask it to return the position of the minimum with `:x` and `:y`.
#
# ```ruby
# min_value, opts = min x: true, y: true
# x_pos = opts['x']
# y_pos = opts['y']
# ```
#
# Now `x_pos` and `y_pos` will have the coordinates of the minimum value.
# There's actually a convenience method for this, {Image#minpos}.
#
# You can also ask for the top *n* minimum, for example:
#
# ```ruby
# min_value, opts = min size: 10, x_array: true, y_array: true
# x_pos = opts['x_array']
# y_pos = opts['y_array']
# ```
#
# Now `x_pos` and `y_pos` will be 10-element arrays.
#
# Because operations are member functions and return the result image, you can
# chain them. For example, you can write:
#
# ```ruby
# result_image = image.real.cos
# ```
#
# to calculate the cosine of the real part of a complex image.
# There are also a full set
# of arithmetic operator overloads, see below.
#
# libvips types are also automatically wrapped. The override looks at the type
# of argument required by the operation and converts the value you supply,
# when it can. For example, {Image#linear} takes a `VipsArrayDouble` as
# an argument
# for the set of constants to use for multiplication. You can supply this
# value as an integer, a float, or some kind of compound object and it
# will be converted for you. You can write:
#
# ```ruby
# result_image = image.linear 1, 3
# result_image = image.linear 12.4, 13.9
# result_image = image.linear [1, 2, 3], [4, 5, 6]
# result_image = image.linear 1, [4, 5, 6]
# ```
#
# And so on. A set of overloads are defined for {Image#linear}, see below.
#
# It does a couple of more ambitious conversions. It will automatically convert
# to and from the various vips types, like `VipsBlob` and `VipsArrayImage`. For
# example, you can read the ICC profile out of an image like this:
#
# ```ruby
# profile = im.get_value "icc-profile-data"
# ```
#
# and profile will be a byte array.
#
# If an operation takes several input images, you can use a constant for all but
# one of them and the wrapper will expand the constant to an image for you. For
# example, {Image#ifthenelse} uses a condition image to pick pixels
# between a then and an else image:
#
# ```ruby
# result_image = condition_image.ifthenelse then_image, else_image
# ```
#
# You can use a constant instead of either the then or the else parts and it
# will be expanded to an image for you. If you use a constant for both then and
# else, it will be expanded to match the condition image. For example:
#
# ```ruby
# result_image = condition_image.ifthenelse [0, 255, 0], [255, 0, 0]
# ```
#
# Will make an image where true pixels are green and false pixels are red.
#
# This is useful for {Image#bandjoin}, the thing to join two or more
# images up bandwise. You can write:
#
# ```ruby
# rgba = rgb.bandjoin 255
# ```
#
# to append a constant 255 band to an image, perhaps to add an alpha channel. Of
# course you can also write:
#
# ```ruby
# result_image = image1.bandjoin image2
# result_image = image1.bandjoin [image2, image3]
# result_image = Vips::Image.bandjoin [image1, image2, image3]
# result_image = image1.bandjoin [image2, 255]
# ```
#
# and so on.
#
# # Logging
#
# Libvips uses g_log() to log warning, debug, info and (some) error messages.
#
# https://developer.gnome.org/glib/stable/glib-Message-Logging.html
#
# You can disable warnings by defining the `VIPS_WARNING` environment variable.
# You can enable info output by defining `VIPS_INFO`.
#
# # Exceptions
#
# The wrapper spots errors from vips operations and raises the {Vips::Error}
# exception. You can catch it in the usual way.
#
# # Automatic YARD documentation
#
# The bulk of these API docs are generated automatically by {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://libvips.github.io/libvips/API/current)
# for more detail.
#
# # Enums
#
# The libvips enums, such as `VipsBandFormat` appear in ruby-vips as Symbols
# like `:uchar`. They are documented as a set of classes for convenience, see
# {Vips::BandFormat}, for example.
#
# # Draw operations
#
# There are two ways of calling the libvips draw operations, like
# {Image#draw_circle} and {Image#draw_line}.
#
# First, you can use them like functions. For example:
#
# ```ruby
# y = x.draw_line 255, 0, 0, x.width, x.height
# ```
#
# This will make a new image, `y`, which is a copy of `x` but with a line
# drawn across it. `x` is unchanged.
#
# This is simple, but will be slow if you want to draw many lines, since
# ruby-vips will make a copy of the whole image each time.
#
# You can use {Image#mutate} to make a {MutableImage}. This is an image which
# is unshared and is only available inside the {Image#mutate} block. Within
# this block, you can use `!` versions of the draw operations to modify images
# and avoid the copy. For example:
#
# ```ruby
# image = image.mutate do |mutable|
#   (0 ... 1).step(0.01) do |i|
#     mutable.draw_line! 255, mutable.width * i, 0, 0, mutable.height * (1 - i)
#   end
# end
# ```
#
# Now each {Image#draw_line} will directly modify the mutable image, saving
# the copy. This is much faster and needs much less memory.
#
# # Metadata read
#
# Use {Image#get_fields} to get a list of the metadata fields that an image
# supports. ICC profiles, for example, are in a field called
# `icc-profile-data`. Use `vipsheader -a something.jpg` at the command-line
# to see all the fields on an image.
#
# Use {Image#get_typeof} to get the type of a field. Types are integers, with
# 0 meaning "no such field". Constants like {GObject::GINT_TYPE} are useful for
# testing field types.
#
# You can read image metadata using {Image#get}. The field value is converted
# to a Ruby value in the obvious way.
#
# # Metadata write
#
# You can also set and remove image metadata fields. Images are immutable, so
# you must make any changes inside a {Image#mutate} block. For example:
#
# ```ruby
# image = image.mutate do |mutable|
#   image.get_fields.each do |field|
#     mutable.remove! field unless field == "icc-profile-data"
#   end
# end
# ```
#
# To remove all metadata except the icc profile.
#
# You can use {MutableImage#set!} to change the value of an existing field,
# and {MutableImage#set_type!} to create a new field with a specified type.
#
# # 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:
#
# ```ruby
# result_image = ((image * [1, 2, 3]).abs < 128) | 4
# ```
#
# # Expansions
#
# Some vips operators take an enum to select an action, for example
# {Image#math} can be used to calculate sine of every pixel like this:
#
# ```ruby
# result_image = image.math :sin
# ```
#
# This is annoying, so the wrapper expands all these enums into separate members
# named after the enum. So you can write:
#
# ```ruby
# result_image = image.sin
# ```
#
# # Convenience functions
#
# The wrapper defines a few extra useful utility functions:
# {Image#get_value}, {Image#set_value}, {Image#bandsplit},
# {Image#maxpos}, {Image#minpos},
# {Image#median}.

module Vips
  extend FFI::Library

  ffi_lib library_name("vips", 42)

  LOG_DOMAIN = "VIPS"
  GLib.set_log_domain LOG_DOMAIN

  # 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

  attach_function :vips_error_buffer, [], :string
  attach_function :vips_error_clear, [], :void
  attach_function :vips_error_freeze, [], :void
  attach_function :vips_error_thaw, [], :void

  # The ruby-vips error class.
  class Error < RuntimeError
    # @param msg [String] The error message. If this is not supplied, grab
    #   and clear the vips error buffer and use that.
    def initialize msg = nil
      if msg
        @details = msg
      elsif Vips.vips_error_buffer != ""
        @details = Vips.vips_error_buffer
        Vips.vips_error_clear
      else
        @details = nil
      end
    end

    # Pretty-print a {Vips::Error}.
    #
    # @return [String] The error message
    def to_s
      if !@details.nil?
        @details
      else
        super.to_s
      end
    end
  end

  attach_function :vips_init, [:string], :int

  if Vips.vips_init($0) != 0
    throw Vips.get_error
  end

  # don't use at_exit to call vips_shutdown, it causes problems with fork, and
  # in any case libvips does this for us

  attach_function :vips_leak_set, [:int], :void
  attach_function :vips_vector_set_enabled, [:int], :void
  attach_function :vips_concurrency_set, [:int], :void

  # vips_foreign_get_suffixes was added in libvips 8.8
  begin
    attach_function :vips_foreign_get_suffixes, [], :pointer
  rescue FFI::NotFoundError
    nil
  end

  # Turn libvips leak testing on and off. Handy for debugging ruby-vips, not
  # very useful for user code.
  def self.leak_set leak
    vips_leak_set((leak ? 1 : 0))
  end

  attach_function :vips_cache_set_max, [:int], :void
  attach_function :vips_cache_set_max_mem, [:int], :void
  attach_function :vips_cache_set_max_files, [:int], :void

  # Set the maximum number of operations that libvips should cache. Set 0 to
  # disable the operation cache. The default is 1000.
  def self.cache_set_max size
    vips_cache_set_max size
  end

  # Set the maximum amount of memory that libvips should use for the operation
  # cache. Set 0 to disable the operation cache. The default is 100mb.
  def self.cache_set_max_mem size
    vips_cache_set_max_mem size
  end

  # Set the maximum number of files libvips should keep open in the
  # operation cache. Set 0 to disable the operation cache. The default is
  # 100.
  def self.cache_set_max_files size
    vips_cache_set_max_files size
  end

  # Set the size of the libvips worker pool. This defaults to the number of
  # hardware threads on your computer. Set to 1 to disable threading.
  def self.concurrency_set n
    vips_concurrency_set n
  end

  # Enable or disable SIMD and the run-time compiler. This can give a nice
  # speed-up, but can also be unstable on some systems or with some versions
  # of the run-time compiler.
  def self.vector_set enabled
    vips_vector_set_enabled(enabled ? 1 : 0)
  end

  # Deprecated compatibility function.
  #
  # Don't use this, instead change GLib::logger.level.
  def self.set_debug debug
    if debug
      GLib.logger.level = Logger::DEBUG
    end
  end

  attach_function :version, :vips_version, [:int], :int
  attach_function :version_string, :vips_version_string, [], :string

  # True if this is at least libvips x.y
  def self.at_least_libvips?(x, y)
    major = version(0)
    minor = version(1)

    major > x || (major == x && minor >= y)
  end

  # Get a list of all supported file suffixes.
  #
  # @return [[String]] array of supported suffixes
  def self.get_suffixes
    # vips_foreign_get_suffixes() was added in libvips 8.8
    return [] unless Vips.respond_to? :vips_foreign_get_suffixes

    array = Vips.vips_foreign_get_suffixes

    names = []
    p = array
    until (q = p.read_pointer).null?
      suff = q.read_string
      GLib.g_free q
      names << suff unless names.include? suff
      p += FFI::Type::POINTER.size
    end
    GLib.g_free array

    names
  end

  LIBRARY_VERSION = Vips.version_string

  # libvips has this arbitrary number as a sanity-check upper bound on image
  # 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/mutableimage"
require "vips/interpolate"
require "vips/region"
require "vips/version"
require "vips/connection"
require "vips/source"
require "vips/sourcecustom"
require "vips/target"
require "vips/targetcustom"