ruby-vips 1.0.6 → 2.0.0

data/lib/vips/object.rb

@@ -0,0 +1,204 @@
+# 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
+
+    # we must init these by hand, since they are usually made on first image
+    # create
+    attach_function :vips_band_format_get_type, [], :GType
+    attach_function :vips_interpretation_get_type, [], :GType
+    attach_function :vips_coding_get_type, [], :GType
+
+    public
+
+    # some handy gtypes
+    IMAGE_TYPE = GObject::g_type_from_name "VipsImage"
+    ARRAY_INT_TYPE = GObject::g_type_from_name "VipsArrayInt"
+    ARRAY_DOUBLE_TYPE = GObject::g_type_from_name "VipsArrayDouble"
+    ARRAY_IMAGE_TYPE = GObject::g_type_from_name "VipsArrayImage"
+    REFSTR_TYPE = GObject::g_type_from_name "VipsRefString"
+    BLOB_TYPE = GObject::g_type_from_name "VipsBlob"
+
+    BAND_FORMAT_TYPE = Vips::vips_band_format_get_type
+    INTERPRETATION_TYPE = Vips::vips_interpretation_get_type
+    CODING_TYPE = Vips::vips_coding_get_type
+
+    private
+
+    attach_function :vips_enum_from_nick, [:string, :GType, :string], :int
+    attach_function :vips_enum_nick, [:GType, :int], :string
+
+    attach_function :vips_value_set_array_double, 
+        [GObject::GValue.ptr, :pointer, :int], :void
+    attach_function :vips_value_set_array_int, 
+        [GObject::GValue.ptr, :pointer, :int], :void
+    attach_function :vips_value_set_array_image, 
+        [GObject::GValue.ptr, :int], :void
+    callback :free_fn, [:pointer], :void
+    attach_function :vips_value_set_blob, 
+        [GObject::GValue.ptr, :free_fn, :pointer, :size_t], :void
+
+    class SizeStruct < FFI::Struct
+        layout :value, :size_t
+    end
+
+    class IntStruct < FFI::Struct
+        layout :value, :int
+    end
+
+    attach_function :vips_value_get_ref_string, 
+        [GObject::GValue.ptr, SizeStruct.ptr], :string
+    attach_function :vips_value_get_array_double, 
+        [GObject::GValue.ptr, IntStruct.ptr], :pointer
+    attach_function :vips_value_get_array_int, 
+        [GObject::GValue.ptr, IntStruct.ptr], :pointer
+    attach_function :vips_value_get_array_image, 
+        [GObject::GValue.ptr, IntStruct.ptr], :pointer
+    attach_function :vips_value_get_blob, 
+        [GObject::GValue.ptr, SizeStruct.ptr], :pointer
+
+    attach_function :type_find, :vips_type_find, [:string, :string], :GType
+
+    class Object < GObject::GObject
+
+        # the layout of the VipsObject struct
+        module ObjectLayout
+            def self.included base
+                base.class_eval do
+                    # don't actually need most of these
+                    layout :parent, GObject::GObject::Struct, 
+                       :constructed, :int,
+                       :static_object, :int,
+                       :argument_table, :pointer,
+                       :nickname, :string,
+                       :description, :string,
+                       :preclose, :int,
+                       :close, :int,
+                       :postclose, :int,
+                       :local_memory, :size_t
+                end
+            end
+        end
+
+        class Struct < GObject::GObject::Struct
+            include ObjectLayout
+
+        end
+
+        class ManagedStruct < GObject::GObject::ManagedStruct
+            include ObjectLayout
+
+        end
+
+        def get_typeof name
+            pspec = GObject::GParamSpecPtr.new
+            argument_class = Vips::ArgumentClassPtr.new
+            argument_instance = Vips::ArgumentInstancePtr.new
+
+            result = Vips::vips_object_get_argument self, name,
+                pspec, argument_class, argument_instance
+            raise Vips::Error if result != 0 
+
+            pspec[:value][:value_type]
+        end
+
+        def get name
+            gtype = get_typeof name
+            gvalue = GObject::GValue.alloc 
+            gvalue.init gtype
+            GObject::g_object_get_property self, name, gvalue
+            result = gvalue.get
+
+            # Vips::log "Vips::Object.get(\"#{name}\"): result = #{result}"
+
+            return result
+        end
+
+        def set name, value
+            # Vips::log "Vips::Object.set: #{name} = #{value}"
+
+            gtype = get_typeof name
+            gvalue = GObject::GValue.alloc 
+            gvalue.init gtype
+            gvalue.set value
+            GObject::g_object_set_property self, name, gvalue
+        end
+
+    end
+
+    class ObjectClass < FFI::Struct
+        # opaque
+    end
+
+    class Argument < FFI::Struct
+        layout :pspec, GObject::GParamSpec.ptr
+    end
+
+    class ArgumentInstance < Argument
+        layout :parent, Argument
+        # rest opaque
+    end
+
+    # enum VipsArgumentFlags 
+    ARGUMENT_REQUIRED = 1
+    ARGUMENT_CONSTRUCT = 2
+    ARGUMENT_SET_ONCE = 4
+    ARGUMENT_SET_ALWAYS = 8
+    ARGUMENT_INPUT = 16
+    ARGUMENT_OUTPUT = 32
+    ARGUMENT_DEPRECATED = 64
+    ARGUMENT_MODIFY = 128
+
+    ARGUMENT_FLAGS = {
+        :required => ARGUMENT_REQUIRED,
+        :construct => ARGUMENT_CONSTRUCT,
+        :set_once => ARGUMENT_SET_ONCE,
+        :set_always => ARGUMENT_SET_ALWAYS,
+        :input => ARGUMENT_INPUT,
+        :output => ARGUMENT_OUTPUT,
+        :deprecated => ARGUMENT_DEPRECATED,
+        :modify => ARGUMENT_MODIFY
+    }
+
+    class ArgumentClass < Argument
+        layout :parent, Argument,
+               :object_class, ObjectClass.ptr,
+               :flags, :uint,
+               :priority, :int,
+               :offset, :ulong_long
+    end
+
+    class ArgumentClassPtr < FFI::Struct
+        layout :value, ArgumentClass.ptr
+    end
+
+    class ArgumentInstancePtr < FFI::Struct
+        layout :value, ArgumentInstance.ptr
+    end
+
+    # just use :pointer, not VipsObject.ptr, to avoid casting gobject
+    # subclasses
+    attach_function :vips_object_get_argument, 
+        [:pointer, :string, 
+         GObject::GParamSpecPtr.ptr, 
+         ArgumentClassPtr.ptr, ArgumentInstancePtr.ptr],
+        :int
+
+    attach_function :vips_object_print_all, [], :void
+
+    attach_function :vips_object_set_from_string, [:pointer, :string], :int
+
+    callback :type_map_fn, [:GType, :pointer], :pointer
+    attach_function :vips_type_map, [:GType, :type_map_fn, :pointer], :pointer
+
+    attach_function :vips_object_get_description, [:pointer], :string
+
+end
+
+

data/lib/vips/operation.rb

@@ -1,19 +1,363 @@
+# 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
+
+    attach_function :vips_cache_operation_build, [:pointer], :pointer
+    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
+
+    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 == nil
+            end
+
+            super value
+        end
+
+        def build 
+            op = Vips::vips_cache_operation_build self 
+            if op == nil
+                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
+
+        def get_flags
+            Vips::vips_operation_get_flags self
+        end
+
+        # not quick! try to call this infrequently
+        def get_construct_args
+            args = []
+
+            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
+                    name = pspec[:name].gsub("-", "_")
+
+                    args << [name, flags] 
+                end
+            end
+
+            return args
+        end
+
+        # search array for the first element to match a predicate ...
+        # search inside subarrays and sub-hashes
+        def self.find_inside object, &block
+            return object if block.call object
+
+            if object.is_a? Enumerable
+                object.find {|value| block.call value, block}
+            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 and value[0].is_a? Array) or 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
 
-    # add a conventience method to Operation
-    # @private
-    class Operation
-        # Fetch arg list, remove boring ones, sort into priority order.
-        def get_args
-            gobject_class = gtype.to_class
-            props = gobject_class.properties.select do |name|
-                flags = get_argument_flags name
-                io = ((flags & :input) | (flags & :output)) != 0
-                dep = (flags & :deprecated) != 0
-                io & (not dep)
-            end
-            args = props.map {|name| Argument.new self, name}
-            args.sort! {|a, b| a.priority - b.priority}
+        # set an operation argument, expanding constants and copying images as
+        # required
+        def set name, value, match_image = nil, flags = 0
+            gtype = get_typeof name
+
+            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 = ""
+            #Vips::log "Vips::VipsOperation.call: name = #{name}, " + 
+            #    "supplied = #{supplied} optional = #{optional} " +
+            #    "option_string = #{option_string}"
+
+            op = Operation.new name
+
+            # find and classify all the arguments the operator can take
+            args = op.get_construct_args
+            required_input = [] 
+            optional_input = {}
+            required_output = [] 
+            optional_output = {}
+            args.each do |name, flags|
+                next if (flags & ARGUMENT_DEPRECATED) != 0
+
+                if (flags & ARGUMENT_INPUT) != 0 
+                    if (flags & ARGUMENT_REQUIRED) != 0 and
+                        required_input << [name, flags]
+                    else
+                        optional_input[name] = flags
+                    end
+                end
+
+                # MODIFY INPUT args count as OUTPUT as well
+                if (flags & ARGUMENT_OUTPUT) != 0 or
+                    ((flags & ARGUMENT_INPUT) != 0 and
+                     (flags & ARGUMENT_MODIFY) != 0)
+                    if (flags & ARGUMENT_REQUIRED) != 0 and
+                        required_output << [name, flags]
+                    else
+                        optional_output[name] = flags
+                    end
+                end
+
+            end
+
+            # so we should have been supplied with n_required_input values, or
+            # n_required_input + 1 if there's a hash of options at the end
+            if not supplied.is_a? Array
+                raise Vips::Error, "unable to call #{name}: " + 
+                    "argument array is not an array"
+            end
+            if not 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
+
+            # very that all supplied_optional keys are in optional_input or
+            # optional_output
+            optional.each do |key, value|
+                arg_name = key.to_s
+
+                if not optional_input.has_key? arg_name and
+                    not 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 = find_inside(supplied) do |value|
+                value.is_a? Image
+            end
+
+            # 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|
+                arg_name = required_input[i][0]
+                flags = required_input[i][1]
+                value = supplied[i]
+
+                op.set arg_name, value, match_image, flags
+            end
+
+            # set all optional inputs
+            optional.each do |key, value|
+                arg_name = key.to_s
+
+                if optional_input.has_key? arg_name
+                    flags = optional_input[arg_name]
+
+                    op.set arg_name, value, match_image, flags
+                end
+            end
+
+            op = op.build
+
+            # get all required results
+            result = []
+            required_output.each do |arg_name, flags|
+                result << op.get(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
+                    flags = optional_output[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
+
+            # Vips::log "Vips::Operation.call: result = #{result}"
+
+            Vips::vips_object_unref_outputs op
+
+            return result
+        end
+
     end
+
 end