ruby-vips 2.2.4 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f4bfc7ec785c930f9f11566a241b0b811c20ada01d38ef9dda7761f0daeb1efd
-  data.tar.gz: 618efc35ab3e798be637da9cead6aff9c8654162054a4104d71ff339348116c2
+  metadata.gz: b025e3dd6e37cb95d8b77fea2351d2c8bef1d711cb8fd600d1532fed3ce606db
+  data.tar.gz: 245512b73bdb8db46af18c499060b2e2ab39ab2976c1eabc4866f0610fc51e0a
 SHA512:
-  metadata.gz: 49b7080c073a31214510bf56ed3cac7d18f5a1aa336b8f517867bab65bfc11b255f6184fddad564e363ae2f9f9bf17deecee6dffcb31af93b64f3a9162801575
-  data.tar.gz: c1253b94ac98fe8d9617d66dc4c47b41021c0f51497b6577dfad020a5e6898b36fee0baa8762e4b3b80ce697e4062fd71c258beb050ec81fb94a767954481040
+  metadata.gz: 28e0163d98af345d4b01536f508a28d052a594ee84e4a171d61960dc1af09c79c92aa063557cb5ff66b38f334c36f18ed3c262c13e68dcacbe65ee8ece277bef
+  data.tar.gz: 7a84837e453159d4126bc6dded6f3a6e3d76fdc43e1725fa6aa5d72b5bb6eeceb2c9240f05c8a4c3f804b56165bff3f0a7129b16b7573805eb38ae6246d7c66c

data/.github/workflows/test.yml

@@ -13,7 +13,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
@@ -47,7 +47,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1

data/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## master
 
+## Version 2.3.0 (2025-12-10)
+
+* move library_name out of the global namespace and into FFI [jcupitt]
+* update docs for libvips 8.18 [jcupitt]
+* add Image#get_gainmap [jcupitt]
+* version bump to 2.3
+
+## Version 2.2.5 (2025-08-20)
+
+* improve NULL pointer handling [dloebl]
+* improve GFlags argument handling [jcupitt]
+* add missing flag and enum docs [jcupitt]
+
 ## Version 2.2.4 (2025-06-05)
 
 * fix write to target test with libvips 8.17 [jcupitt]
@@ -18,8 +31,8 @@
 
 ## Version 2.2.1 (2024-02-21)
 
-* add `Vips.block_untrusted` method to block all untrusted operations. Only for libvips >= 8.13. [Docs](https://www.libvips.org/API/current/libvips-vips.html#vips-block-untrusted-set). [#382](https://github.com/libvips/ruby-vips/pull/382) [aglushkov](https://github.com/aglushkov)
-* add `Vips.block` method to block specific operation. Only for libvips >= 8.13. [Docs](https://www.libvips.org/API/current/VipsOperation.html#vips-operation-block-set). [#382](https://github.com/libvips/ruby-vips/pull/382) [aglushkov](https://github.com/aglushkov)
+* add `Vips.block_untrusted` method to block all untrusted operations. Only for libvips >= 8.13. [Docs](https://www.libvips.org/API/current/func.block_untrusted_set.html). [#382](https://github.com/libvips/ruby-vips/pull/382) [aglushkov](https://github.com/aglushkov)
+* add `Vips.block` method to block specific operation. Only for libvips >= 8.13. [Docs](https://www.libvips.org/API/current/type_func.Operation.block_set.html). [#382](https://github.com/libvips/ruby-vips/pull/382) [aglushkov](https://github.com/aglushkov)
 * `new_from_source` keeps a ref to the source object [taylorthurlow]
 * some fixes to object references system
 

data/README.md

@@ -52,7 +52,7 @@ im = Vips::Image.new_from_file filename
 # put im at position (100, 100) in a 3000 x 3000 pixel image, 
 # make the other pixels in the image by mirroring im up / down / 
 # left / right, see
-# https://libvips.github.io/libvips/API/current/libvips-conversion.html#vips-embed
+# https://www.libvips.org/API/current/method.Image.embed.html
 im = im.embed 100, 100, 3000, 3000, extend: :mirror
 
 # multiply the green (middle) band by 2, leave the other two alone
@@ -80,7 +80,7 @@ should always work.
 See the `Vips` section in the docs for a [tutorial introduction with
 examples](https://www.rubydoc.info/gems/ruby-vips/Vips).
 
-The [libvips reference manual](https://libvips.github.io/libvips/API/current/)
+The [libvips reference manual](https://www.libvips.org/API/current/)
 has a complete explanation of every method.
 
 The [`example/`](https://github.com/libvips/ruby-vips/tree/master/example)

data/VERSION

@@ -1 +1 @@
-2.2.4
+2.3.0

data/example/inheritance_with_refcount.rb

@@ -21,6 +21,7 @@ end
 
 module Libc
   extend FFI::Library
+
   ffi_lib FFI::Library::LIBC
 
   attach_function :malloc, [:size_t], :pointer
@@ -29,6 +30,7 @@ end
 
 module GLib
   extend FFI::Library
+
   ffi_lib "gobject-2.0"
 
   def self.set_log_domain(_domain)
@@ -142,6 +144,7 @@ end
 
 module Vips
   extend FFI::Library
+
   ffi_lib "vips"
 
   LOG_DOMAIN = "VIPS"

data/lib/vips/combine.rb

@@ -0,0 +1,10 @@
+module Vips
+  # How to combine values, see for example {Image#compass}.
+  #
+  # * `:max` take the maximum of the possible values
+  # * `:sum` sum all the values
+  # * `:min` take the minimum value
+
+  class Combine < Symbol
+  end
+end

data/lib/vips/fail_on.rb

@@ -0,0 +1,15 @@
+module Vips
+  # How sensitive loaders are to errors, from never stop (very insensitive),
+  # to stop on the smallest warning (very sensitive).
+  #
+  # Each implies the ones before it, so `:error` implies `:truncated`, for
+  # example.
+  #
+  # *   `:none` never stop
+  # *   `:truncated` stop on image truncated, nothing else
+  # *   `:error` stop on serious error or truncation
+  # *   `:warning` stop on anything, even warnings
+
+  class FailOn < Symbol
+  end
+end

data/lib/vips/foreign_dz_container.rb

@@ -0,0 +1,10 @@
+module Vips
+  # The container format to use
+  #
+  # *   `:fs` write tiles to the filesystem
+  # *   `:zip` write tiles to a zip file
+  # *   `:szi` write to a szi file
+
+  class ForeignDzContainer < Symbol
+  end
+end

data/lib/vips/foreign_dz_depth.rb

@@ -0,0 +1,10 @@
+module Vips
+  # How many pyramid layers to create.
+  #
+  # *   `:onepixel` create layers down to 1x1 pixel
+  # *   `:onetile` create layers down to 1x1 tile
+  # *   `:one` only create a single layer
+
+  class ForeignDzDepth < Symbol
+  end
+end

data/lib/vips/foreign_dz_layout.rb

@@ -0,0 +1,12 @@
+module Vips
+  # What directory layout and metadata standard to use.
+  #
+  # *   `:dz` use DeepZoom directory layout
+  # *   `:zoomify` use Zoomify directory layout
+  # *   `:google` use Google maps directory layout
+  # *   `:iiif` use IIIF v2 directory layout
+  # *   `:iiif3` use IIIF v3 directory layout
+
+  class ForeignDzLayout < Symbol
+  end
+end

data/lib/vips/foreign_heif_compression.rb

@@ -0,0 +1,11 @@
+module Vips
+  # The compression format to use inside a HEIF container
+  #
+  # *   `:hevc` x265
+  # *   `:avc` x264
+  # *   `:jpeg` jpeg
+  # *   `:av1` aom
+
+  class ForeignHeifCompression < Symbol
+  end
+end

data/lib/vips/foreign_heif_encoder.rb

@@ -0,0 +1,11 @@
+module Vips
+  # The selected encoder to use.
+  #
+  # *   `:auto` auto
+  # *   `:rav1e` RAV1E
+  # *   `:svt` SVT-AV1
+  # *   `:x265` x265
+
+  class ForeignHeifEncoder < Symbol
+  end
+end

data/lib/vips/foreign_keep.rb

@@ -0,0 +1,14 @@
+module Vips
+  # Savers can be given a set of metadata items to keep.
+  #
+  # *   `:none` remove all metadata
+  # *   `:exif` keep EXIF metadata
+  # *   `:xmp` keep XMP metadata
+  # *   `:iptc` keep IPTC metadata
+  # *   `:icc` keep ICC profiles
+  # *   `:gainmap` keep the gainmap metadata
+  # *   `:other` keep other metadata
+
+  class ForeignKeep < Symbol
+  end
+end

data/lib/vips/foreign_png_filter.rb

@@ -0,0 +1,13 @@
+module Vips
+  # The set of filters for PNG save. See http://www.w3.org/TR/PNG-Filters.html
+  #
+  # *   `:none` no filtering
+  # *   `:sub` difference to the left
+  # *   `:up` difference up
+  # *   `:avg` average of left and up
+  # *   `:paeth` pick best neighbor predictor automatically
+  # *   `:all` adaptive
+
+  class ForeignPngFilter < Symbol
+  end
+end

data/lib/vips/foreign_ppm_format.rb

@@ -0,0 +1,12 @@
+module Vips
+  # The netpbm file format to save as.
+  #
+  # *   `:pbm` portable bitmap
+  # *   `:pgm` portable greymap
+  # *   `:ppm` portable pixmap
+  # *   `:pfm` portable float map
+  # *   `:pnm` portable anymap
+
+  class ForeignPpmFormat < Symbol
+  end
+end

data/lib/vips/foreign_subsample.rb

@@ -0,0 +1,10 @@
+module Vips
+  # Set subsampling mode.
+  #
+  # *   `:auto` prevent subsampling when quality >= 90
+  # *   `:on` always perform subsampling
+  # *   `:off` never perform subsampling
+
+  class ForeignSubsample < Symbol
+  end
+end

data/lib/vips/foreign_tiff_compression.rb

@@ -0,0 +1,16 @@
+module Vips
+  # The compression types supported by the tiff writer.
+  #
+  # *   `:none` no compression
+  # *   `:jpeg` jpeg compression
+  # *   `:deflate` deflate (zip) compression
+  # *   `:packbits` packbits compression
+  # *   `:ccittfax4` fax4 compression
+  # *   `:lzw` LZW compression
+  # *   `:webp` WEBP compression
+  # *   `:zstd` ZSTD compression
+  # *   `:jp2k` JP2K compression
+
+  class ForeignTiffCompression < Symbol
+  end
+end

data/lib/vips/foreign_tiff_predictor.rb

@@ -0,0 +1,10 @@
+module Vips
+  # The predictor can help deflate and lzw compression.
+  #
+  # *   `:none` no prediction
+  # *   `:horizontal` horizontal differencing
+  # *   `:float` float predictor
+
+  class ForeignTiffPredictor < Symbol
+  end
+end

data/lib/vips/foreign_tiff_resunit.rb

@@ -0,0 +1,9 @@
+module Vips
+  # Use inches or centimeters as the resolution unit for a tiff file.
+  #
+  # *   `:cm` use centimeters
+  # *   `:inch` use inches
+
+  class ForeignTiffResunit < Symbol
+  end
+end

data/lib/vips/foreign_webp_preset.rb

@@ -0,0 +1,13 @@
+module Vips
+  # Tune lossy encoder settings for different image types.
+  #
+  # *   `:default` default preset
+  # *   `:picture` digital picture, like portrait, inner shot
+  # *   `:photo` outdoor photograph, with natural lighting
+  # *   `:drawing` hand or line drawing, with high-contrast details
+  # *   `:icon` small-sized colorful images
+  # *   `:text` text-like
+
+  class ForeignWebpPreset < Symbol
+  end
+end

data/lib/vips/gvalue.rb

@@ -25,7 +25,7 @@ module GObject
       :data, [:ulong_long, 2]
 
     # convert an enum value (str/symb/int) into an int ready for libvips
-    def self.from_nick(gtype, value)
+    def self.enum_from_nick(gtype, value)
       value = value.to_s if value.is_a? Symbol
 
       if value.is_a? String
@@ -40,6 +40,43 @@ module GObject
       value
     end
 
+    # compatibility ... we used to call it this, perhaps someone has used this
+    # internal method
+    def self.from_nick(gtype, value)
+      GValue.enum_from_nick(gtype, value)
+    end
+
+    # convert an flags value (array[str/symb/int] | str/symb/int) into an
+    # int ready for libvips
+    def self.flags_from_nick(gtype, value)
+      if value.is_a? String
+        # libvips will parse strings like "sub|up" etc.
+        name = value.tr("_", "-")
+        value = Vips.vips_flags_from_nick "ruby-vips", gtype, name
+      else
+        value = [value] if !value.is_a? Array
+
+        # convert each item to a set of bits, OR them together
+        result = 0
+        value.map do |item|
+          item = item.to_s if item.is_a? Symbol
+          if item.is_a? String
+            name = item.tr("_", "-")
+            item = Vips.vips_flags_from_nick "ruby-vips", gtype, name
+            if item == -1
+              raise Vips::Error
+            end
+          end
+
+          result |= item
+        end
+
+        value = result
+      end
+
+      value
+    end
+
     # convert an int enum back into a symbol
     def self.to_nick(gtype, enum_value)
       enum_name = Vips.vips_enum_nick gtype, enum_value
@@ -148,10 +185,11 @@ module GObject
       else
         case fundamental
         when GFLAGS_TYPE
-          ::GObject.g_value_set_flags self, value
+          flags_value = GValue.flags_from_nick(self[:gtype], value)
+          ::GObject.g_value_set_flags self, flags_value
 
         when GENUM_TYPE
-          enum_value = GValue.from_nick(self[:gtype], value)
+          enum_value = GValue.enum_from_nick(self[:gtype], value)
           ::GObject.g_value_set_enum self, enum_value
 
         when GOBJECT_TYPE

data/lib/vips/image.rb

@@ -50,6 +50,10 @@ module Vips
     attach_function :vips_addalpha, [:pointer, :pointer, :varargs], :int
   end
 
+  if Vips.at_least_libvips?(8, 18)
+    attach_function :vips_image_get_gainmap, [:pointer], :pointer
+  end
+
   # move these three lines to mutableimage when we finally remove set and
   # remove in this class
   attach_function :vips_image_set,
@@ -114,12 +118,12 @@ module Vips
     end
 
     def self.complex? format
-      format_number = GObject::GValue.from_nick BAND_FORMAT_TYPE, format
+      format_number = GObject::GValue.enum_from_nick BAND_FORMAT_TYPE, format
       Vips.vips_band_format_iscomplex(format_number) != 0
     end
 
     def self.float? format
-      format_number = GObject::GValue.from_nick BAND_FORMAT_TYPE, format
+      format_number = GObject::GValue.enum_from_nick BAND_FORMAT_TYPE, format
       Vips.vips_band_format_isfloat(format_number) != 0
     end
 
@@ -380,7 +384,7 @@ module Vips
         size = data.bytesize
       end
 
-      format_number = GObject::GValue.from_nick BAND_FORMAT_TYPE, format
+      format_number = GObject::GValue.enum_from_nick BAND_FORMAT_TYPE, format
       vi = Vips.vips_image_new_from_memory data, size,
         width, height, bands, format_number
       raise Vips::Error if vi.null?
@@ -405,7 +409,7 @@ module Vips
     # @param format [Symbol] band format
     # @return [Image] the loaded image
     def self.new_from_memory_copy data, width, height, bands, format
-      format_number = GObject::GValue.from_nick BAND_FORMAT_TYPE, format
+      format_number = GObject::GValue.enum_from_nick BAND_FORMAT_TYPE, format
 
       if data.is_a?(FFI::Pointer)
         if data.size == UNKNOWN_POINTER_SIZE
@@ -471,9 +475,10 @@ module Vips
     def self.matrix_from_array width, height, array
       ptr = FFI::MemoryPointer.new :double, array.length
       ptr.write_array_of_double array
-      image = Vips.vips_image_new_matrix_from_array width, height,
+      img_ptr = Vips.vips_image_new_matrix_from_array width, height,
         ptr, array.length
-      Vips::Image.new image
+      raise Vips::Error if img_ptr.null?
+      Vips::Image.new img_ptr
     end
 
     # Create a new Image from a 1D or 2D array. A 1D array becomes an
@@ -534,7 +539,6 @@ module Vips
       end
 
       image = Vips::Image.matrix_from_array width, height, array
-      raise Vips::Error if image.nil?
 
       image.mutate do |mutable|
         # be careful to set them as double
@@ -700,7 +704,7 @@ module Vips
     def write_to_memory
       len = Vips::SizeStruct.new
       ptr = Vips.vips_image_write_to_memory self, len
-      raise Vips::Error if ptr.nil?
+      raise Vips::Error if ptr.null?
 
       # wrap up as an autopointer
       ptr = FFI::AutoPointer.new(ptr, GLib::G_FREE)
@@ -797,8 +801,33 @@ module Vips
       names
     end
 
+    # Get the gainmap (if any) from an image.
+    #
+    # After modifying the gainmap, you should write it back to the image in a
+    # mutable block, see [#mutate], in the field "gainmap".
+    #
+    # For example:
+    #
+    # ```ruby
+    # gainmap = image.get_gainmap
+    # unless gainmap.nil?
+    #   new_gainmap = gainmap.crop left, top, width, height
+    #   image = image.mutate do |x|
+    #     x.set_type! Vips::IMAGE_TYPE, "gainmap", new_gainmap
+    #   end
+    # end
+    # ```
+    #
+    # @return [Image] the gainmap image, or nil
+    def get_gainmap
+      if Vips.at_least_libvips?(8, 18)
+        vi = Vips.vips_image_get_gainmap self
+        Image.new(vi) unless vi.null?
+      end
+    end
+
     # Mutate an image with a block. Inside the block, you can call methods
-    # which modify the image, such as setting or removing metadata, or
+    # which modify the image, such as setting or removing metadata or
     # modifying pixels.
     #
     # For example:
@@ -1173,11 +1202,7 @@ module Vips
     # @return [Image] result of inequality
     def != other
       # for equality, we must allow tests against nil
-      if other.nil?
-        true
-      else
-        call_enum "relational", other, :noteq
-      end
+      other.nil? || call_enum("relational", other, :noteq)
     end
 
     # Fetch bands using a number or a range
@@ -1319,7 +1344,7 @@ module Vips
       end
 
       mode = mode.map do |x|
-        GObject::GValue.from_nick Vips::BLEND_MODE_TYPE, x
+        GObject::GValue.enum_from_nick Vips::BLEND_MODE_TYPE, x
       end
 
       Vips::Image.composite([self] + overlay, mode, **opts)

data/lib/vips/intent.rb

@@ -0,0 +1,12 @@
+module Vips
+  # The rendering intent.
+  #
+  # * `:perceptual` perceptual rendering intent
+  # * `:relative` relative colorimetric rendering intent
+  # * `:saturation` saturation rendering intent
+  # * `:absolute` absolute colorimetric rendering intent
+  # * `:auto` the rendering intent that the profile suggests
+
+  class Intent < Symbol
+  end
+end

data/lib/vips/interpolate.rb

@@ -50,7 +50,7 @@ module Vips
     def initialize name
       name = name.to_s if name.is_a? Symbol
       pointer = Vips.vips_interpolate_new name
-      raise Vips::Error if pointer.nil?
+      raise Vips::Error if pointer.null?
 
       super(pointer)
     end

data/lib/vips/interpretation.rb

@@ -6,7 +6,6 @@ module Vips
   # * `:multiband` generic many-band image
   # * `:b_w` some kind of single-band image
   # * `:histogram` a 1D image, eg. histogram or lookup table
-  # * `:fourier` image is in fourier space
   # * `:xyz` the first three bands are CIE XYZ
   # * `:lab` pixels are in CIE Lab space
   # * `:cmyk` the first four bands are in CMYK space
@@ -16,12 +15,14 @@ module Vips
   # * `:lch` pixels are in CIE LCh space
   # * `:labs` CIE LAB coded as three signed 16-bit values
   # * `:srgb` pixels are sRGB
-  # * `:hsv` pixels are HSV
-  # * `:scrgb` pixels are scRGB
   # * `:yxy` pixels are CIE Yxy
+  # * `:fourier` image is in fourier space
   # * `:rgb16` generic 16-bit RGB
   # * `:grey16` generic 16-bit mono
   # * `:matrix` a matrix
+  # * `:scrgb` pixels are scRGB
+  # * `:hsv` pixels are HSV
+
   class Interpretation < Symbol
   end
 end

data/lib/vips/kernel.rb

@@ -4,16 +4,19 @@ module Vips
   #
   # At least these should be available:
   #
-  # *   `:nearest` Nearest-neighbour interpolation.
-  # *   `:linear` Linear interpolation.
-  # *   `:cubic` Cubic interpolation.
-  # *   `:lanczos2` Two-lobe Lanczos
-  # *   `:lanczos3` Three-lobe Lanczos
+  # *   `:nearest` nearest-neighbour interpolation
+  # *   `:linear` linear interpolation
+  # *   `:cubic` cubic interpolation
+  # *   `:mitchell` Mitchell interpolation
+  # *   `:lanczos2` two-lobe Lanczos
+  # *   `:lanczos3` three-lobe Lanczos
+  # *   `:mks2013` convolve with Magic Kernel Sharp 2013
+  # *   `:mks2021` convolve with Magic Kernel Sharp 2021
   #
   #  For example:
   #
   #  ```ruby
-  #  im = im.resize 3, :kernel => :lanczos2
+  #  im = im.resize 3, kernel: :lanczos2
   #  ```
 
   class Kernel < Symbol