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

  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. 
  #
  # 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, 
    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
  attach_function :vips_argument_map, [:pointer,
                                       :argument_map_fn,
                                       :pointer, :pointer], :pointer

  OPERATION_SEQUENTIAL = 1
  OPERATION_NOCACHE = 4
  OPERATION_DEPRECATED = 8

  OPERATION_FLAGS = {
    sequential: OPERATION_SEQUENTIAL,
    nocache: OPERATION_NOCACHE,
    deprecated: OPERATION_DEPRECATED
  }

  attach_function :vips_operation_get_flags, [:pointer], :int

  # Introspect a vips operation and return a large structure containing
  # 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

    @@introspect_cache = {}

    def initialize name
      @op = Operation.new name
      @args = []
      @required_input = []
      @optional_input = {}
      @required_output = []
      @optional_output = {}

      # find all the arguments the operator can take
      @op.argument_map do |pspec, argument_class, _argument_instance|
        flags = argument_class[:flags]
        if (flags & ARGUMENT_CONSTRUCT) != 0
          # 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]
          }
        end
      end

      @args.each do |details|
        arg_name = details[:arg_name]
        flags = details[:flags]

        if (flags & ARGUMENT_INPUT) != 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
              @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
            @required_output << details
          else
            # again, allow deprecated optional args
            @optional_output[arg_name] = details
          end
        end
      end
    end

    # Yard comment generation needs a little more introspection. We add this
    # extra metadata in a separate method to keep the main path as fast as
    # we can.
    def add_yard_introspection name
      @name = name
      @description = Vips::vips_object_get_description @op
      @flags = Vips::vips_operation_get_flags @op
      @member_x = nil
      @method_args = []

      @args.each do |details|
        arg_name = details[:arg_name]
        flags = details[:flags]
        gtype = details[:gtype]

        details[:yard_name] = arg_name == "in" ? "im" : arg_name
        pspec = @op.get_pspec arg_name
        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 
          # of
          if @member_x == nil && gtype == IMAGE_TYPE
            @member_x = details 
          else
            @method_args << details
          end
        end
      end
    end

    def self.get name
      @@introspect_cache[name] ||= Introspect.new name
    end

    def self.get_yard name
      introspect = Introspect.get name
      introspect.add_yard_introspection name
      introspect
    end

  end

  class Operation < Object
    # the layout of the VipsOperation struct
    module OperationLayout
      def self.included base
        base.class_eval do
          layout :parent, Object::Struct
          # rest opaque
        end
      end
    end

    class Struct < Object::Struct
      include OperationLayout
    end

    class ManagedStruct < Object::ManagedStruct
      include OperationLayout
    end

    def initialize value
      # 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
        raise Vips::Error if value.null?
      end

      super value
    end

    def build
      op = Vips::vips_cache_operation_build self
      if op.null?
        Vips::vips_object_unref_outputs self
        raise Vips::Error
      end

      return Operation.new op
    end

    def argument_map &block
      fn = Proc.new 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
    end

    # 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
        end
      else
        return object if yield object
      end

      return nil
    end

    # expand a constant into an image
    def self.imageize match_image, value
      return value if value.is_a? Image

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

    # set an operation argument, expanding constants and copying images as
    # required
    def set name, value, match_image, flags, gtype
      if gtype == IMAGE_TYPE
        value = Operation::imageize match_image, value

        if (flags & ARGUMENT_MODIFY) != 0
          # make sure we have a unique copy
          value = value.copy.copy_memory
        end
      elsif gtype == ARRAY_IMAGE_TYPE
        value = value.map { |x| Operation::imageize match_image, x }
      end

      super name, value
    end

    public

    # This is the public entry point for the vips binding. {call} will run
    # any vips operation, for example:
    #
    # ```ruby
    # out = Vips::Operation.call "black", [100, 100], {:bands => 12}
    # ```
    #
    # will call the C function
    #
    # ```C
    # vips_black( &out, 100, 100, "bands", 12, NULL );
    # ```
    #
    # There are {Image#method_missing} hooks which will run {call} for you
    # on {Image} for undefined instance or class methods. So you can also
    # write:
    #
    # ```ruby
    # out = Vips::Image.black 100, 100, bands: 12
    # ```
    #
    # Or perhaps:
    #
    # ```ruby
    # x = Vips::Image.black 100, 100
    # y = x.invert
    # ```
    #
    # to run the `vips_invert()` operator.
    #
    # There are also a set of operator overloads and some convenience
    # functions, see {Image}.
    #
    # If the operator needs a vector constant, {call} will turn a scalar
    # into a
    # vector for you. So for `x.linear a, b`, which calculates
    # `x * a + b` where `a` and `b` are vector constants, you can write:
    #
    # ```ruby
    # x = Vips::Image.black 100, 100, bands: 3
    # y = x.linear 1, 2
    # y = x.linear [1], 4
    # y = x.linear [1, 2, 3], 4
    # ```
    #
    # or any other combination. The operator overloads use this facility to
    # support all the variations on:
    #
    # ```ruby
    # x = Vips::Image.black 100, 100, bands: 3
    # y = x * 2
    # y = x + [1,2,3]
    # y = x % [1]
    # ```
    #
    # Similarly, wherever an image is required, you can use a constant. The
    # constant will be expanded to an image matching the first input image
    # argument. For example, you can write:
    #
    # ```
    # x = Vips::Image.black 100, 100, bands: 3
    # y = x.bandjoin 255
    # ```
    #
    # to add an extra band to the image where each pixel in the new band has
    # the constant value 255.

    def self.call name, supplied, optional = {}, option_string = ""
      GLib::logger.debug("Vips::VipsOperation.call") {
        "name = #{name}, supplied = #{supplied}, " +
          "optional = #{optional}, option_string = #{option_string}"
      }

      introspect = Introspect.get name
      required_input = introspect.required_input
      required_output = introspect.required_output
      optional_input = introspect.optional_input
      optional_output = introspect.optional_output

      unless supplied.is_a? 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"
      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}."
      end

      # all supplied_optional keys should be in optional_input or
      # optional_output
      optional.each do |key, _value|
        arg_name = key.to_s

        unless optional_input.has_key?(arg_name) ||
            optional_output.has_key?(arg_name)
          raise Vips::Error, "unable to call #{name}: " +
                             "unknown option #{arg_name}"
        end
      end

      # the first image arg is the thing we expand constants to match ...
      # we need to find it
      #
      # 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 }

      op = Operation.new 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
          raise Vips::Error
        end
      end

      # set all required inputs
      required_input.each_index do |i|
        details = required_input[i]
        arg_name = details[:arg_name]
        flags = details[:flags]
        gtype = details[:gtype]
        value = supplied[i]

        op.set arg_name, value, match_image, flags, gtype
      end

      # set all optional inputs
      optional.each do |key, value|
        next if value.nil?

        arg_name = key.to_s

        if optional_input.has_key? arg_name
          details = optional_input[arg_name]
          flags = details[:flags]
          gtype = details[:gtype]

          op.set arg_name, value, match_image, flags, gtype
        end
      end

      op = op.build

      # get all required results
      result = []
      required_output.each do |details|
        result << op.get(details[:arg_name])
      end

      # fetch all optional ones
      optional_results = {}
      optional.each do |key, _value|
        arg_name = key.to_s

        if optional_output.has_key? arg_name
          optional_results[arg_name] = op.get arg_name
        end
      end

      result << optional_results if optional_results != {}

      if result.length == 1
        result = result.first
      elsif result.length == 0
        result = nil
      end

      GLib::logger.debug("Vips::Operation.call") { "result = #{result}" }

      Vips::vips_object_unref_outputs op

      return result
    end
  end
end